@memberjunction/ai-agents 6.2.0-edge.1 → 6.2.0-edge.3

package/dist/base-agent.js

@@ -12,16 +12,18 @@
  */
 import { FileStorageEngineBase, MJEnvironmentEntityExtended } from '@memberjunction/core-entities';
 import { BuildActionToolSet, FilterDeclarableActions, SanitizeToolName } from './native-tools/action-tool-builder.js';
-import { BuildNativeToolSet, SUB_AGENT_TOOL_PREFIX } from './native-tools/control-tools.js';
+import { BuildNativeToolSet, COMPLETE_TASK_TOOL, SUB_AGENT_TOOL_PREFIX } from './native-tools/control-tools.js';
 import { BuildAssistantToolCallTurn, BuildToolResultTurn, CompactToolResultContent } from './native-tools/tool-result-turns.js';
 import { LooksLikeLoopEnvelope } from './native-tools/dual-channel.js';
 import { ResolvePromptRunUserID } from "@memberjunction/ai-core-plus";
-import { Metadata, RunView, LogStatus, LogStatusEx, LogError, LogErrorEx, IsVerboseLoggingEnabled, DatabaseProviderBase } from '@memberjunction/core';
+import { Metadata, RunView, LogStatus, LogStatusEx, LogError, LogErrorEx, IsVerboseLoggingEnabled, DatabaseProviderBase, ToPlainJSON } from '@memberjunction/core';
 import { AgentRunWatchdog } from './agent-run-watchdog.js';
 import { AIPromptRunner, GetToolCallingDecision } from '@memberjunction/ai-prompts';
-import { BaseRealtimeModel, GetAIAPIKey, IsPrefixPromptCache } from '@memberjunction/ai';
+import { BaseRealtimeModel, GetAIAPIKey, CredentialScopeAllows, MakeAIAPIKeyResolver, IsPrefixPromptCache } from '@memberjunction/ai';
 import { BaseAgentType } from './agent-types/base-agent-type.js';
-import { CopyScalarsAndArrays, JSONValidator, MJGlobal, NormalizeUUID, SafeExpressionEvaluator, UUIDsEqual, EscapeSQLString } from '@memberjunction/global';
+import { ProviderRubricEngine } from '@memberjunction/rubrics';
+import { ExecuteSelfCheck, PickSelfCheckLink } from './self-check.js';
+import { CopyScalarsAndArrays, JSONValidator, MJGlobal, NormalizeUUID, SafeExpressionEvaluator, UUIDsEqual, EscapeSQLString, IsPlainObject, CleanAndParseJSON } from '@memberjunction/global';
 // token optimization via @memberjunction/context-crush (SmartCrusher/CacheAligner-inspired)
 import { CrushJSON, DescribeCrush, PartitionStablePrefix } from '@memberjunction/context-crush';
 // AST-aware code reduction (CodeCompressor-inspired) — opt-in per agent type
@@ -32,6 +34,7 @@ import { BuildRealtimeOverridesJson, BuildVoiceMannerSection, GetNarrationPaceMs
 import { SelectRealtimeVendorForModel } from './realtime/realtime-vendor-resolution.js';
 import { RealtimeClientSessionService, WarnOnUnmatchedProviderVoice } from './realtime/realtime-client-session-service.js';
 import { BuildRealtimeAgentFraming } from './realtime/realtime-tool-broker.js';
+import { ReadHostTools, ReadTrimmedString } from './realtime/bridge-host-params.js';
 import { RealtimeRecordingController } from './realtime/realtime-recording-capture.js';
 import { ResolveRecordingStorageAccountID, StoreRealtimeRecording } from './realtime/realtime-recording-store.js';
 import { AIEngine } from '@memberjunction/aiengine';
@@ -44,7 +47,7 @@ import { FormatToolResultSection, FormatToolErrorSection, RenderToolResultData,
 import { PriorTurnToolResultCache } from './prior-turn-tool-result-cache.js';
 import { PromptComponentResolver, InjectScopedPromptParts } from './prompt-component-resolver.js';
 import { ScopedPromptConfigResolver, ApplyScopedPromptConfig } from './scoped-prompt-config-resolver.js';
-import { StringifyForPersistence, AIPromptParams, ChildPromptParam, ConversationUtility, ParseFileOutputRef, parseAssignmentStrategy, ResolveClientTools, initAgentRunStep, finalizeAgentRunStep, AgentRunStepSaveQueue, ExtractPromptResultText, GetTaskGraphSubmitter, SystemPlaceholderManager } from '@memberjunction/ai-core-plus';
+import { StringifyForPersistence, AIPromptParams, ChildPromptParam, ConversationUtility, ParseFileOutputRef, parseAssignmentStrategy, ResolveClientTools, initAgentRunStep, finalizeAgentRunStep, AgentRunStepSaveQueue, ExtractPromptResultText, GetTaskGraphSubmitter, SummarizeDecisionAnswers, SystemPlaceholderManager } from '@memberjunction/ai-core-plus';
 import { ActionResult, RunActionParams } from '@memberjunction/actions-base';
 import { TemplateEngineServer } from '@memberjunction/templates';
 import { RuntimeStateFragmentBuilder, EscapeRuntimeStateTagsInMessage } from './runtime-state-fragment.js';
@@ -55,6 +58,13 @@ import { PayloadManager } from './PayloadManager.js';
 import { ScratchpadManager } from './ScratchpadManager.js';
 import { ArtifactToolManager } from './ArtifactToolManager.js';
 import { MemoryWriteManager } from './MemoryWriteManager.js';
+import { AgentDecisionService } from './AgentDecisionService.js';
+import { PayloadFeedbackManager } from './PayloadFeedbackManager.js';
+import { DEFAULT_LOOP_AGENT_PROMPT_PARAMS, MAX_DECISION_CALLS_PER_TURN, MAX_DECISION_REQUESTS_PER_TURN, ResolveFinishIfMode } from './agent-types/loop-agent-prompt-params.js';
+import { FinishIfModeWarnings } from './finish-if-mode-warnings.js';
+import { ApplyCatalogNarrowing, BuildCatalogNarrowingQuestions, CatalogNarrowingCandidatesToAsk, CatalogNarrowingNote, CATALOG_NARROWING_FIND_ACTIONS, IsAlwaysShownAction, IsCatalogListNarrowed, NoCatalogNarrowing, OpeningRequestText, ReachableCatalogNarrowingLimits, ResolveCatalogNarrowingLimits, SelectCatalogNarrowing, } from './catalog-narrowing.js';
+import { BuildDecisionDiscoveryOptionSet, BuildDecisionDiscoveryQuestions, CanSearchEntities, DECISION_DISCOVERY_MAX_RECORDED_IDS, DECISION_DISCOVERY_MIN_CONFIDENCE, DECISION_DISCOVERY_MIN_OPTIONS, DECISION_DISCOVERY_TIMEOUT_MS, DecisionDiscoveryAgentSearch, DecisionDiscoveryFromResult, DecisionDiscoveryRunnableAgents, DecisionPromptOptionCap, FailedDecisionDiscovery, HostAllowedAgentIDs, IsDecisionDiscoveryOn, IsOpeningTurn, MentionsAgent, } from './decision-discovery.js';
+import { BuildFinishIfQuestions, CapFinishIfState, FINISH_IF_STATE_EXCERPT, FormatActionForFinishIf, FormatSubAgentForFinishIf, JudgeFinishIf } from './finish-if-state.js';
 import { PipelineExecutor, PipelineToolRegistry, ActionInvocable, ArtifactToolInvocable, BuildPipelineToolDocs, formatFinalOutput, summarizePipelineStages, } from './pipeline/index.js';
 // The ONE payload-mapping dialect. Loop agents and the task-graph dispatcher read the same authored
 // mapping strings, so these must be the same functions rather than two copies that agree today.
@@ -127,6 +137,19 @@ export class CircuitBreakerActionResult extends ActionResult {
         this.Reason = Reason;
     }
 }
+/** The top-level `reasoning` and `message` of a prompt's JSON response, when it has them. */
+function responseReasoningAndMessage(result) {
+    const parsed = typeof result === 'string' ? CleanAndParseJSON(result) : result;
+    if (typeof parsed !== 'object' || parsed === null) {
+        return {};
+    }
+    const reasoning = 'reasoning' in parsed ? parsed.reasoning : undefined;
+    const message = 'message' in parsed ? parsed.message : undefined;
+    return {
+        Reasoning: typeof reasoning === 'string' ? reasoning : undefined,
+        Message: typeof message === 'string' ? message : undefined
+    };
+}
 export class BaseAgent {
     constructor() {
         /**
@@ -285,6 +308,10 @@ export class BaseAgent {
          * Allows agents to explore input artifacts on demand.
          */
         this._artifactToolManager = new ArtifactToolManager();
+        /**
+         * Service for evaluating agent decisions inline via fast decision models.
+         */
+        this._agentDecisionService = new AgentDecisionService();
         /**
          * Manages conversation-history retrieval tools for the current agent run.
          * Armed only when the run has a conversationId (the cross-turn context gate).
@@ -311,6 +338,18 @@ export class BaseAgent {
          * @private
          */
         this._effectiveSubAgents = [];
+        /**
+         * The request that opened the run: the last user message when it started, before the framework
+         * added anything. Catalog narrowing judges the catalog against it.
+         * @private
+         */
+        this._openingRequest = '';
+        /**
+         * Whether the run answers its conversation's opening request ({@link IsOpeningTurn}), read from
+         * the messages it started with. Decision discovery asks about no other turn.
+         * @private
+         */
+        this._isOpeningTurn = false;
         /**
          * IDs of skills already activated during this run. Prevents re-activation from re-appending
          * the same instructions to context / re-pushing duplicate actionChanges/subAgentChanges entries
@@ -460,6 +499,20 @@ export class BaseAgent {
          * unshifted onto `conversationMessages` by the shared {@link AgentMemoryContextBuilder}.
          */
         this._injectedRAG = null;
+        /**
+         * Checks execution guardrails and modifies next step if limits are exceeded.
+         * This method is called after validation but before execution of non-terminal steps.
+         *
+         * @param params - Execution parameters
+         * @param nextStep - The validated next step
+         * @param currentPayload - Current payload
+         * @param agentRun - Current agent run
+         * @param currentStep - Current execution step
+         * @returns Modified next step if guardrails exceeded, or original next step
+         * @protected
+         */
+        this._selfCheckAttemptsByRun = new Map();
+        this._selfCheckLinkByAgent = new Map();
         /**
          * Determines the request type ID based on the Chat step's context.
          * - If the responseForm has only approve/reject-style buttons, uses "Approval"
@@ -1109,6 +1162,8 @@ export class BaseAgent {
      * @protected
      */
     get FileOutputs() { return this._fileOutputs; }
+    /** The longest the catalog narrowing decision may take before the run shows the full catalog. */
+    static { this.CATALOG_NARROWING_TIMEOUT_MS = 30000; }
     /** The skills activated so far in this run (requested or self-activated), in activation order. */
     get ActivatedSkillIDs() {
         return this._activatedSkillIDs;
@@ -1563,6 +1618,10 @@ export class BaseAgent {
             this._dynamicActionLimits = {};
             this._mediaOutputs = [];
             this._messageLifecycleCallback = params.onMessageLifecycle;
+            this._catalogNarrowing = undefined;
+            this._openingRequest = OpeningRequestText(params.conversationMessages);
+            this._runExecutionScope = this.runPromptExecutionScope(params);
+            this._isOpeningTurn = IsOpeningTurn(params.conversationMessages);
             // Resolve storage account for file artifacts
             this._resolvedStorageAccountId = await this.getStorageAccountID(wrappedParams);
             // Check for cancellation after Phase 1
@@ -1624,7 +1683,10 @@ export class BaseAgent {
                 // Carry the previous turn's tool results forward (no-op without a
                 // conversationId). Runs here so the results are in the messages before
                 // the pre-turn compaction check and the first prompt.
-                this.injectPriorTurnToolResults(wrappedParams)
+                this.injectPriorTurnToolResults(wrappedParams),
+                // Decision discovery (plan Task 3.1), off unless the decisionsEnabled and decisionDiscovery prompt
+                // params are true: may add a <suggested_agent> system message, within DECISION_DISCOVERY_TIMEOUT_MS.
+                this.InjectDecisionDiscovery(params.agent, params.contextUser, wrappedParams.conversationMessages, params.data)
             ]);
             // Inject scope-resolved prompt parts (role-faithful) for this agent's prompt, alongside
             // memory/RAG. Synchronous — parts are cached on AIEngine. Uses the same run scope.
@@ -1713,6 +1775,9 @@ export class BaseAgent {
             // consumers that re-read `params` after the call see what they
             // passed in, not our chained signal.
             params.cancellationToken = upstreamToken;
+            // A cancellation, or an error thrown out of the step loop, leaves any held decision
+            // requests unasked. The terminate path has already logged and cleared its own.
+            this.skipHeldDecisions(params, this.runEndForHeldDecisions());
             this.releasePerRunDataCache();
             await this.finalizeRun(this.deriveRunOutcome());
         }
@@ -1888,9 +1953,20 @@ export class BaseAgent {
         const selfNames = Array.isArray(params.data?.realtimeSelfNames)
             ? (params.data?.realtimeSelfNames).filter((n) => typeof n === 'string')
             : undefined;
+        const hostTools = ReadHostTools(params.data?.realtimeHostTools);
         return {
             CoAgent: params.agent,
             TargetAgentID: targetID,
+            HostTools: hostTools,
+            HostFraming: ReadTrimmedString(params.data?.realtimeHostFraming, 'realtimeHostFraming'),
+            PriorTranscript: ReadTrimmedString(params.data?.realtimePriorTranscript, 'realtimePriorTranscript'),
+            ConversationID: ReadTrimmedString(params.data?.conversationId, 'conversationId'),
+            // The run's runtime API keys, so the bridged voice session mints on the caller's key when
+            // the run carries one for the realtime driver (the same run-key → platform order as
+            // GetAIAPIKey; realtime does not consult MJ Credentials). Absent ⇒ platform keys, as before.
+            // CreateBridgeRealtimeSession (the LiveKit / telephony factory) passes no apiKeys today.
+            APIKeys: params.apiKeys,
+            CredentialScope: params.CredentialScope,
             AgentSessionID: params.data?.agentSessionId ?? '',
             PreferredModelID: modelID,
             ConfigOverridesJson: BuildRealtimeOverridesJson(modelID, voice) ?? undefined,
@@ -1928,13 +2004,22 @@ export class BaseAgent {
         // would dead-end whenever the top model lacked a key — e.g. a power-11 model with no env key
         // (Inworld/AssemblyAI) outranking GPT Realtime — and surface "No usable Realtime model" even though
         // a usable model exists. This mirrors the same fix in RealtimeClientSessionService.
+        // The run's runtime API keys, in GetAIAPIKey's order: the run's key for a driver class, else
+        // the platform's. That is the legacy tier of prompt key resolution — a prompt consults MJ
+        // Credentials / AICredentialBindings first, and realtime does not consult them at all.
+        //
+        // This also affects WHICH vendor runs the session, deliberately. Vendor selection walks
+        // candidates by priority and takes the first whose key resolves, so an organization that
+        // brings its own credential for a vendor we hold no platform key for now reaches that
+        // vendor — which is the point of bringing your own key, not a side effect of it.
+        const resolveAPIKey = MakeAIAPIKeyResolver(params.apiKeys, undefined, params.CredentialScope);
         const candidates = this.selectRealtimeModelCandidates(params.agent, overrideModelID);
         for (const model of candidates) {
-            const vendor = SelectRealtimeVendorForModel(model.ID);
+            const vendor = SelectRealtimeVendorForModel(model.ID, resolveAPIKey);
             if (!vendor) {
                 continue;
             }
-            const apiKey = GetAIAPIKey(vendor.DriverClass);
+            const apiKey = resolveAPIKey(vendor.DriverClass);
             if (!apiKey) {
                 continue;
             }
@@ -2216,6 +2301,7 @@ export class BaseAgent {
                 parentDepth: this._depth,
                 configurationId: params.configurationId,
                 apiKeys: params.apiKeys,
+                CredentialScope: params.CredentialScope,
                 data: params.data,
                 verbose: params.verbose,
                 // Progress streams BOTH to the runner's narration consumer (request.OnProgress —
@@ -2799,6 +2885,7 @@ export class BaseAgent {
             // Check if we should continue or terminate
             if (nextStep.terminate) {
                 continueExecution = false;
+                this.skipHeldDecisions(params, 'the run ended after the step that carried them');
                 this.logStatus(`🏁 Agent '${params.agent.Name}' terminating after ${stepCount} steps with result: ${nextStep.step}`, true, params);
             }
             else {
@@ -2873,6 +2960,25 @@ export class BaseAgent {
         }
         return 'combined';
     }
+    /**
+     * The observability context memory injection runs under for an agent run: the run's ID, the next
+     * step number, and a callback that adds each rerank step to the run's steps. A rerank step carries
+     * the rerank's prompt run, whose cost and token rollups include a prompt-backed reranker's own
+     * prompt runs, so the run's totals and its `MaxCostPerRun` / `MaxTokensPerRun` guardrails count
+     * them. Undefined when there is no run.
+     *
+     * @param run - The current agent run, or null before one exists
+     */
+    MemoryObservability(run) {
+        if (!run) {
+            return undefined;
+        }
+        return {
+            agentRunID: run.ID,
+            stepNumber: (run.Steps?.length || 0) + 1,
+            OnStepCreated: step => run.Steps.push(step),
+        };
+    }
     /**
      * Inject notes and examples into agent context memory.
      * Called automatically before agent execution if injection is enabled on the agent.
@@ -2894,9 +3000,7 @@ export class BaseAgent {
         // Delegate the orchestration to the shared, reusable builder so both BaseAgent and the
         // Realtime agent type inject memory identically. The observability context and verbose
         // status logging are derived from this instance and passed through.
-        const observability = this._agentRun
-            ? { agentRunID: this._agentRun.ID, stepNumber: (this._agentRun.Steps?.length || 0) + 1 }
-            : undefined;
+        const observability = this.MemoryObservability(this._agentRun);
         const result = await new AgentMemoryContextBuilder().InjectContextMemory(input, agent, userId, companyId, contextUser, conversationMessages, primaryScopeEntityId, primaryScopeRecordId, secondaryScopes, secondaryScopeConfig, observability, (message, verboseOnly) => this.logStatus(message, verboseOnly));
         // Store for inclusion in result (externally observable behavior preserved)
         this._injectedMemory = result;
@@ -2961,6 +3065,302 @@ export class BaseAgent {
         this._injectedRAG = result;
         return result;
     }
+    /**
+     * Decision discovery (plan Task 3.1): suggests the agent to delegate to before the first prompt.
+     *
+     * Runs in parallel with the rest of Phase 2 of `Execute()`, and only when the merged agent-type
+     * prompt params set `decisionsEnabled: true` (the master switch, {@link DecisionsEnabled}) and
+     * `decisionDiscovery: true`, the run answers its conversation's opening request
+     * ({@link IsOpeningTurn}), and that request @mentions no agent. A follow-up turn is never asked
+     * about: it may be continuing work with an agent already engaged, and a suggestion must not pull
+     * the agent away from it. One decision asks which of the agents the user may run (and the host
+     * allows) should handle the request, and whether a specialist should. When both answers are
+     * confident, a `<suggested_agent>` system message is unshifted onto `conversationMessages`, the
+     * way pre-execution RAG adds `<retrieved_context>`. Each discovery is recorded as one
+     * `Agent discovery` Decision step.
+     *
+     * Fails safe: an error, a timeout, a cancelled run, an unusable answer or an unsure one adds
+     * nothing, so the agent behaves as it would without discovery. So do fewer than
+     * {@link DECISION_DISCOVERY_MIN_OPTIONS} options. Never delays the first prompt by more than
+     * {@link DECISION_DISCOVERY_TIMEOUT_MS}, and never throws.
+     *
+     * The any-applies question does not name the options, so the decision cannot say that none of
+     * them fits: see {@link DECISION_DISCOVERY_APPLIES_INSTRUCTIONS} for why it stays that way for now.
+     *
+     * @param agent - The agent being executed.
+     * @param contextUser - The user whose run permission decides the options.
+     * @param conversationMessages - The mutated message array that flows to the LLM (the suggestion is unshifted here).
+     * @param data - The run's `ExecuteAgentParams.data`. Its `__agentTypePromptParams` overrides the agent's prompt
+     *   params, and its `ALL_AVAILABLE_AGENTS`, when an array, is the host's allow-list: no other agent is suggested.
+     */
+    async InjectDecisionDiscovery(agent, contextUser, conversationMessages, data) {
+        try {
+            const override = data?.__agentTypePromptParams;
+            const overrides = IsPlainObject(override) ? override : undefined;
+            if (!this.isDecisionDiscoveryOnFor(agent, overrides) || !conversationMessages) {
+                return;
+            }
+            if (!this._openingRequest || !contextUser) {
+                this.logStatus(`Decision discovery skipped for '${agent.Name}': the run has no ${contextUser ? 'user message' : 'context user'}`, true);
+                return;
+            }
+            if (!this._isOpeningTurn) {
+                this.logStatus(`Decision discovery skipped for '${agent.Name}': a follow-up turn, which may continue with an agent already engaged`, true);
+                return;
+            }
+            if (MentionsAgent(this._openingRequest, AIEngine.Instance.Agents, agent.ID)) {
+                this.logStatus(`Decision discovery skipped for '${agent.Name}': the request @mentions an agent`, true);
+                return;
+            }
+            const promptParams = this.decisionDiscoveryPromptParams(agent, overrides);
+            const outcome = await this.runDecisionDiscovery(agent, contextUser, promptParams, HostAllowedAgentIDs(data));
+            if (outcome.Injected && outcome.Message) {
+                conversationMessages.unshift({ role: 'system', content: outcome.Message });
+                this.logStatus(`Decision discovery suggested '${outcome.Answer?.Agent.Name}' to '${agent.Name}'`, true);
+            }
+        }
+        catch (error) {
+            this.warnDecisionDiscovery(agent, error instanceof Error ? error.message : String(error));
+        }
+    }
+    /**
+     * Whether discovery is on for this run: the master switch ({@link DecisionsEnabled}) and
+     * `decisionDiscovery` are both on. Read without rebuilding the merged prompt params, since it is
+     * asked on every run of every agent: each setting from the per-run override when it sets one,
+     * otherwise from the agent's base params, cached on AIEngine with its base catalog. Only a cold
+     * cache builds them.
+     */
+    isDecisionDiscoveryOnFor(agent, overrides) {
+        let base;
+        const paramsSetting = (key) => {
+            if (overrides && key in overrides) {
+                return overrides;
+            }
+            base ??= this.cachedBasePromptParams(agent) ?? this.buildDecisionDiscoveryPromptParams(agent, undefined);
+            return base;
+        };
+        return this.DecisionsEnabled(paramsSetting('decisionsEnabled')) && IsDecisionDiscoveryOn(paramsSetting('decisionDiscovery'));
+    }
+    /**
+     * The run's merged agent-type prompt params (schema defaults < agent < per-run overrides), once
+     * discovery is on: the cached base params when there is no override, otherwise built.
+     */
+    decisionDiscoveryPromptParams(agent, overrides) {
+        const cached = overrides ? undefined : this.cachedBasePromptParams(agent);
+        return cached ?? this.buildDecisionDiscoveryPromptParams(agent, overrides);
+    }
+    /** The agent's base prompt params (no per-run overrides), from the base catalog AIEngine caches, when it holds one. */
+    cachedBasePromptParams(agent) {
+        return AIEngine.Instance.GetAgentBaseCatalog(agent.ID)?.baseAgentTypePromptParams;
+    }
+    /** Builds the merged prompt params, as `gatherPromptTemplateData` does. */
+    buildDecisionDiscoveryPromptParams(agent, overrides) {
+        const agentType = AIEngine.Instance.AgentTypes.find(at => UUIDsEqual(at.ID, agent.TypeID));
+        return this.buildAgentTypePromptParams(agentType, agent, overrides);
+    }
+    /**
+     * Records one `Agent discovery` step around a bounded discovery, and returns what it found. A
+     * failed discovery is logged as a warning; an unsure one only in verbose logs, except that an
+     * answer from a model with no discovery calibration is warned about once per model, because
+     * then discovery can never suggest anything.
+     */
+    async runDecisionDiscovery(agent, contextUser, promptParams, hostAllowedIDs) {
+        const promptName = typeof promptParams.decisionPromptName === 'string'
+            ? promptParams.decisionPromptName
+            : AgentDecisionService.DEFAULT_PROMPT_NAME;
+        const step = await this.startDecisionDiscoveryStep(contextUser, promptName);
+        const outcome = await this.boundDecisionDiscovery(signal => this.discoverAgent(agent, contextUser, promptName, hostAllowedIDs, signal), step);
+        await this.finishDecisionDiscoveryStep(step, outcome);
+        if (!outcome.Succeeded) {
+            this.warnDecisionDiscovery(agent, outcome.Reason ?? 'unknown error');
+        }
+        else if (!outcome.Injected) {
+            if (outcome.UncalibratedModel) {
+                BaseAgent.warnUncalibratedDiscoveryModel(outcome.UncalibratedModel);
+            }
+            this.logStatus(`Decision discovery for '${agent.Name}' suggested no agent: ${outcome.Reason}`, true);
+        }
+        return outcome;
+    }
+    /** The answering models already warned about as having no discovery calibration, so each is warned about once per process. */
+    static { this._uncalibratedDiscoveryModelsWarned = new Set(); }
+    /**
+     * Warns, once per model, that discovery answered by a model with no discovery calibration
+     * suggests nothing. That happens when a decision model is added or renamed, when a vendor model
+     * moves to another version (Jev's `APIName`), or when LLM Decision answers through a chat model
+     * other than the one its calibration was fitted on; without the warning the only trace is each
+     * `Agent discovery` step's reason.
+     */
+    static warnUncalibratedDiscoveryModel(model) {
+        if (BaseAgent._uncalibratedDiscoveryModelsWarned.has(model)) {
+            return;
+        }
+        BaseAgent._uncalibratedDiscoveryModelsWarned.add(model);
+        LogErrorEx({
+            message: `Decision discovery answered by ${model} suggests nothing: the model has no discovery calibration `
+                + '(DECISION_DISCOVERY_CALIBRATION), so its answers are treated as unsure. Fit one with the agent-discovery '
+                + 'Decision Eval, or check that the model was not renamed or moved to another version.',
+            severity: 'warning',
+            category: 'DecisionDiscovery',
+        });
+    }
+    /**
+     * Runs `discover` until it finishes, {@link DECISION_DISCOVERY_TIMEOUT_MS} passes, or the run is
+     * cancelled. A timeout or a cancellation aborts the signal `discover` was given, which aborts the
+     * decision call, and returns a failed discovery at once. What `discover` returns after that
+     * suggests nothing, but the prompt run of its decision call is still linked to `step` once it
+     * settles ({@link linkLateDecisionPromptRun}), so the run counts the call's cost.
+     */
+    async boundDecisionDiscovery(discover, step) {
+        const controller = new AbortController();
+        let stoppedOutcome;
+        const stopped = new Promise(resolve => controller.signal.addEventListener('abort', () => {
+            stoppedOutcome = FailedDecisionDiscovery(String(controller.signal.reason));
+            resolve(stoppedOutcome);
+        }, { once: true }));
+        const runToken = this._executeParams?.cancellationToken;
+        const relayRunAbort = () => controller.abort('the run was cancelled');
+        if (runToken?.aborted) {
+            relayRunAbort();
+        }
+        else {
+            runToken?.addEventListener('abort', relayRunAbort, { once: true });
+        }
+        const timeoutMS = DECISION_DISCOVERY_TIMEOUT_MS;
+        const timer = setTimeout(() => controller.abort(`the decision timed out after ${timeoutMS}ms`), timeoutMS);
+        try {
+            const discovering = discover(controller.signal);
+            const outcome = await Promise.race([discovering, stopped]);
+            if (outcome === stoppedOutcome) {
+                this.linkLateDecisionPromptRun(step, discovering.then(late => late.Result));
+            }
+            return outcome;
+        }
+        catch (error) {
+            return FailedDecisionDiscovery(error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            clearTimeout(timer);
+            runToken?.removeEventListener('abort', relayRunAbort);
+        }
+    }
+    /**
+     * The discovery itself: the options, rebuilt from the permitted catalog, then one decision about
+     * the opening request, and what its answer means. Never throws.
+     */
+    async discoverAgent(agent, contextUser, promptName, hostAllowedIDs, signal) {
+        try {
+            const { Options: options, Error: optionsError, ...rest } = await this.decisionDiscoveryOptionSet(agent, contextUser, promptName, hostAllowedIDs);
+            const sizes = { ...rest, OptionCount: options.length };
+            if (optionsError) {
+                return { ...FailedDecisionDiscovery(optionsError), ...sizes };
+            }
+            if (options.length < DECISION_DISCOVERY_MIN_OPTIONS) {
+                return { Injected: false, Succeeded: true, Reason: `there are ${options.length} agents to choose from, fewer than the ${DECISION_DISCOVERY_MIN_OPTIONS} a suggestion needs, so nothing was asked`, ...sizes };
+            }
+            if (signal.aborted) {
+                return { ...FailedDecisionDiscovery(String(signal.reason)), ...sizes };
+            }
+            const result = await this._agentDecisionService.Ask({
+                State: this._openingRequest,
+                Questions: BuildDecisionDiscoveryQuestions(options),
+                ContextUser: contextUser,
+                AgentID: agent.ID,
+                PromptName: promptName,
+                CancellationToken: signal,
+                ExecutionScope: this._runExecutionScope,
+            });
+            return { ...DecisionDiscoveryFromResult(result, options, DECISION_DISCOVERY_MIN_CONFIDENCE), ...sizes };
+        }
+        catch (error) {
+            return FailedDecisionDiscovery(error instanceof Error ? error.message : String(error));
+        }
+    }
+    /**
+     * The Choice's options, rebuilt on every call and never cached ({@link BuildDecisionDiscoveryOptionSet}):
+     * from AIEngine's current catalog, the agents the user may run, the decision prompt's option cap,
+     * and the semantic search over the opening request when the provider can run it.
+     */
+    async decisionDiscoveryOptionSet(agent, contextUser, promptName, hostAllowedIDs) {
+        const provider = this.ProviderToUse;
+        return BuildDecisionDiscoveryOptionSet({
+            Agents: await DecisionDiscoveryRunnableAgents(AIEngine.Instance.Agents, contextUser),
+            RunningAgentID: agent.ID,
+            HostAllowedIDs: hostAllowedIDs,
+            DeclaredCap: DecisionPromptOptionCap(AIEngine.Instance, promptName),
+            Search: CanSearchEntities(provider) ? DecisionDiscoveryAgentSearch(provider, this._openingRequest, contextUser) : undefined,
+        });
+    }
+    /** Opens the `Agent discovery` Decision step. Without a run there is no step. */
+    async startDecisionDiscoveryStep(contextUser, promptName) {
+        if (!this._agentRun) {
+            return undefined;
+        }
+        try {
+            return await this.createStepEntity({
+                stepType: 'Decision',
+                stepName: 'Agent discovery',
+                contextUser,
+                inputData: {
+                    request: this._openingRequest,
+                    promptName,
+                    minConfidence: DECISION_DISCOVERY_MIN_CONFIDENCE,
+                    timeoutMS: DECISION_DISCOVERY_TIMEOUT_MS,
+                },
+            });
+        }
+        catch (error) {
+            LogError(`Could not record the agent discovery step: ${error instanceof Error ? error.message : String(error)}`);
+            return undefined;
+        }
+    }
+    /**
+     * Finalizes the `Agent discovery` step: the answer, whether it was injected, the host allow-list,
+     * the agents left out for having no description (at most {@link DECISION_DISCOVERY_MAX_RECORDED_IDS}
+     * IDs), any narrowing, and the call's usage.
+     */
+    async finishDecisionDiscoveryStep(step, outcome) {
+        if (!step) {
+            return;
+        }
+        const result = outcome.Result;
+        // Like every decision call, it counts toward the run's cost and tokens through its step
+        if (result) {
+            this.attachDecisionPromptRun(step, result);
+        }
+        const answer = outcome.Answer;
+        const withoutDescription = outcome.WithoutDescription ?? [];
+        await this.finalizeStepEntity(step, outcome.Succeeded, outcome.Succeeded ? undefined : outcome.Reason, {
+            injected: outcome.Injected,
+            reason: outcome.Reason,
+            catalogSize: outcome.CatalogSize,
+            hostAllowList: outcome.HostAllowListSize === undefined ? false : { size: outcome.HostAllowListSize },
+            withoutDescription: { count: withoutDescription.length, agentIds: withoutDescription.slice(0, DECISION_DISCOVERY_MAX_RECORDED_IDS) },
+            options: outcome.OptionCount,
+            optionLimit: outcome.OptionLimit,
+            declaredOptionCap: outcome.DeclaredOptionCap,
+            narrowed: outcome.NarrowedFrom === undefined ? false : { by: 'semantic search', from: outcome.NarrowedFrom, to: outcome.OptionCount },
+            answer: answer ? {
+                agentId: answer.Agent.ID,
+                agent: answer.Agent.Name,
+                confidence: answer.Confidence,
+                anyApplies: answer.AnyApplies,
+                probabilities: answer.Probabilities,
+            } : undefined,
+            executionTimeMS: result?.executionTimeMS,
+            tokensUsed: result?.tokensUsed,
+            model: result?.DecisionResult?.ResolvedModel ?? result?.modelInfo?.modelName,
+            promptRunId: result?.promptRun?.ID,
+        });
+    }
+    /** Logs that decision discovery failed, so nothing was suggested. */
+    warnDecisionDiscovery(agent, reason) {
+        LogErrorEx({
+            message: `Decision discovery for '${agent.Name}' failed, so no agent is suggested: ${reason}`,
+            severity: 'warning',
+            category: 'DecisionDiscovery',
+        });
+    }
     /**
      * Converts UI markup (@{...} syntax) in user messages to plain text.
      * This prevents agents from being confused by UI-specific JSON syntax and reduces token usage.
@@ -3437,6 +3837,9 @@ export class BaseAgent {
             return;
         }
         // ...and a per-agent-ACTION gate: rows that opt out are removed before the tool set is built.
+        // Catalog narrowing (plan Task 3.7) does not apply here, by design: it shortens the prose
+        // catalog only. A call to an undeclared tool is a Retry, and this mode has no `Actions`
+        // envelope step, so a hidden action or sub-agent left undeclared could not be called at all.
         const actions = FilterDeclarableActions(this.getEffectiveActionsForValidation(params.agent.ID), AIEngine.Instance.AgentActions.filter((aa) => UUIDsEqual(aa.AgentID, params.agent.ID)));
         const subAgents = this.getEffectiveSubAgentsForValidation(params.agent.ID);
         if (actions.length === 0 && subAgents.length === 0) {
@@ -3464,15 +3867,22 @@ export class BaseAgent {
     /**
      * The `tool_choice` for this turn (§8.3).
      *
-     * `'auto'` normally, `'none'` on the last turn this run will be allowed.
+     * `'auto'` normally; on the last turn this run will be allowed, a forced `complete_task` call.
      *
      * **Why the final turn is special.** A tool call is a request to continue: the framework runs
      * the action, feeds the result back, and the model decides again. On the last permitted
      * iteration there is no "again" — the limit check fires the moment the turn returns, so the
      * action is executed, paid for, and its result discarded, and the run ends with no answer for
      * the user because the model spent its last turn asking a question instead of answering one.
-     * Forcing `'none'` converts that turn into what the framework actually needs from it: a
-     * terminal envelope.
+     * The final turn is forced to what the framework actually needs from it: a terminal answer.
+     *
+     * **Why `complete_task` and not `'none'`.** Under implicit control flow, `'none'` forbids the
+     * model's only way to store its result — `payload_change_request` and `complete_task` are tools
+     * too — so a forced `'none'` turn can end the run but never deliver the payload. Naming
+     * `complete_task` forces the one call that does both. A model that is NOT on implicit control
+     * flow never receives `complete_task` (the runner strips control tools), and the runner then
+     * downgrades the named choice to `'none'`: the envelope turn the hybrid needs. Providers also
+     * enforce a named choice more reliably than `'none'`.
      *
      * **What this does NOT fix.** Models call a tool on a measurable share of turns whose right
      * answer was chat, completion or delegation. Those are not predictable
@@ -3480,14 +3890,14 @@ export class BaseAgent {
      * address them. That belongs to the prompt, and is why the native-mode Actions section names
      * the cases explicitly.
      *
-     * Subclasses may narrow this further; the base contract is that a forced `'none'` must never be
-     * relaxed to `'auto'` on a turn the framework has already decided is terminal.
+     * Subclasses may narrow this further; the base contract is that a forced terminal choice must
+     * never be relaxed to `'auto'` on a turn the framework has already decided is terminal.
      *
      * @param params The run parameters, for the per-run iteration override
-     * @returns `'none'` on the final permitted iteration, otherwise `'auto'`
+     * @returns `{ name: 'complete_task' }` on the final permitted iteration, otherwise `'auto'`
      */
     resolveToolChoiceForTurn(params) {
-        return this.isFinalPermittedIteration(params) ? 'none' : 'auto';
+        return this.isFinalPermittedIteration(params) ? { name: COMPLETE_TASK_TOOL } : 'auto';
     }
     /**
      * Whether the turn currently being prepared is the last one this run will be allowed.
@@ -3668,6 +4078,7 @@ export class BaseAgent {
             if (params.apiKeys && params.apiKeys.length > 0) {
                 childPromptParams.apiKeys = params.apiKeys;
             }
+            childPromptParams.CredentialScope = params.CredentialScope;
             // Pass through configurationId to both parent and child prompts if provided
             if (params.configurationId) {
                 promptParams.configurationId = params.configurationId;
@@ -3703,6 +4114,10 @@ export class BaseAgent {
             promptParams.apiKeys = params.apiKeys;
             this.logStatus(`🔑 Using ${params.apiKeys.length} API key(s) provided at runtime`, true, params);
         }
+        promptParams.CredentialScope = params.CredentialScope;
+        if (!CredentialScopeAllows(params.CredentialScope, 'Environment')) {
+            this.logStatus(`🔒 Credential scope is ${params.CredentialScope}: the platform's environment API keys will not be used`, true, params);
+        }
         // Thread the per-request provider so prompt run records are saved through the isolated provider
         promptParams.provider = params.provider || this._activeProvider;
         // Overlay scope-resolved run settings (model / vendor / configuration / effort / sampling
@@ -4741,23 +5156,96 @@ export class BaseAgent {
         // Default behavior: let Chat propagate up (no remapping)
         return nextStep;
     }
-    /**
-     * Checks execution guardrails and modifies next step if limits are exceeded.
-     * This method is called after validation but before execution of non-terminal steps.
-     *
-     * @param params - Execution parameters
-     * @param nextStep - The validated next step
-     * @param currentPayload - Current payload
-     * @param agentRun - Current agent run
-     * @param currentStep - Current execution step
-     * @returns Modified next step if guardrails exceeded, or original next step
-     * @protected
-     */
+    async applySelfCheck(params, nextStep, agentRun, currentPayload) {
+        if (params.cancellationToken?.aborted)
+            return null;
+        const provider = params.provider || this._activeProvider;
+        let row = this._selfCheckLinkByAgent.get(agentRun.AgentID);
+        if (row === undefined) {
+            try {
+                const view = RunView.FromMetadataProvider(provider);
+                const found = await view.RunView({
+                    EntityName: 'MJ: AI Agent Rubrics',
+                    ExtraFilter: `AgentID='${agentRun.AgentID}' AND Purpose='SelfCheck' AND Status='Active'`,
+                    OrderBy: 'ID',
+                    ResultType: 'simple',
+                }, params.contextUser);
+                if (!found.Success) {
+                    LogError(`Self-check lookup failed, so the run continues: ${found.ErrorMessage || 'the view did not succeed'}`);
+                    return null;
+                }
+                row = PickSelfCheckLink((found.Results ?? [])) ?? null;
+                this._selfCheckLinkByAgent.set(agentRun.AgentID, row);
+            }
+            catch (error) {
+                LogError(`Self-check lookup failed, so the run continues: ${error instanceof Error ? error.message : String(error)}`);
+                return null;
+            }
+        }
+        if (!row?.RubricID)
+            return null;
+        const link = {
+            Purpose: String(row.Purpose ?? ''),
+            Status: String(row.Status ?? ''),
+            MaxAttempts: row.MaxSelfCheckAttempts ?? null,
+            rubricId: String(row.RubricID),
+            passThreshold: row.PassThreshold ?? null,
+            evaluatorConfig: row.EvaluatorConfig ?? null,
+        };
+        const attempt = (this._selfCheckAttemptsByRun.get(agentRun.ID) ?? 0) + 1;
+        this._selfCheckAttemptsByRun.set(agentRun.ID, attempt);
+        const record = async (step) => {
+            const saved = await this.createStepEntity({
+                stepType: 'Validation',
+                stepName: 'Rubric self-check',
+                contextUser: params.contextUser,
+                inputData: { rubricEvaluationId: step.EvaluationId, passed: step.Passed },
+            });
+            await this.finalizeStepEntity(saved, step.Passed, step.Message || undefined);
+        };
+        try {
+            const outcome = await ExecuteSelfCheck({
+                engine: ProviderRubricEngine(provider, params.contextUser, this.runPromptExecutionScope(params)),
+                link,
+                runId: agentRun.ID,
+                agentKind: this.AgentTypeInstance?.constructor?.name === 'LoopAgentType' ? 'loop' : 'flow',
+                attempt,
+                candidate: { Message: nextStep.message, Payload: nextStep.newPayload ?? currentPayload },
+                record,
+            });
+            if (outcome.step === 'Success')
+                return null;
+            if (outcome.step === 'Retry')
+                return { ...nextStep, step: 'Retry', message: outcome.decision.Message };
+            return { ...nextStep, step: 'Failed', message: outcome.decision.Message, errorMessage: outcome.decision.Message };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            LogError(`Self-check could not be saved, so the run continues: ${message}`);
+            try {
+                await record({ Passed: false, Message: message });
+            }
+            catch (recordError) {
+                LogError(`Self-check validation step could not be recorded: ${recordError instanceof Error ? recordError.message : String(recordError)}`);
+            }
+            return null;
+        }
+    }
+    /** Runs the self-check when a success exit did not pass through the guardrail hook. */
+    async selfCheckSuccess(params, step, payload) {
+        if (step.step !== 'Success' || !this._agentRun)
+            return step;
+        const checked = await this.applySelfCheck(params, step, this._agentRun, payload);
+        return checked ?? step;
+    }
     async checkExecutionGuardrails(params, nextStep, currentPayload, agentRun, currentStep) {
-        // Skip guardrail checks for terminal steps
-        if (nextStep.step === 'Success' || nextStep.step === 'Failed' || nextStep.step === 'Chat') {
+        if (nextStep.step === 'Failed' || nextStep.step === 'Chat') {
             return nextStep;
         }
+        if (nextStep.step === 'Success') {
+            const checked = await this.applySelfCheck(params, nextStep, agentRun, currentPayload);
+            return checked ?? nextStep;
+        }
         // Check if any guardrails are exceeded
         const guardrailResult = await this.hasExceededAgentRunGuardrails(params, agentRun);
         if (guardrailResult.exceeded) {
@@ -5668,14 +6156,24 @@ The context is now within limits. Please retry your request with the recovered c
         this.appendNativeAssistantTurn(params, guardrailCheckedStep);
         // if we need to retry make sure we add the retry message to the conversation messages
         if (guardrailCheckedStep.step === 'Retry' && guardrailCheckedStep.payloadToolCallId && guardrailCheckedStep.nativeTurn?.sendResultsNatively) {
-            // the payload-only turn is answered as a tool result for the payload_change_request call.
+            // A payload-only turn, or a complete_task that failed Success validation, is answered as a
+            // tool result for that call — the feedback is what the model reads next.
             params.conversationMessages.push(BuildToolResultTurn([{
                     toolCallId: guardrailCheckedStep.payloadToolCallId,
-                    toolName: 'payload_change_request',
+                    toolName: this.nativeToolNameForCall(guardrailCheckedStep, guardrailCheckedStep.payloadToolCallId),
                     content: guardrailCheckedStep.retryInstructions || 'Payload change applied.',
                     isError: false
                 }], { turnAdded: this._promptTurnCount, messageType: 'action-result' }));
         }
+        else if (guardrailCheckedStep.step === 'Success' && guardrailCheckedStep.payloadToolCallId && guardrailCheckedStep.nativeTurn?.sendResultsNatively) {
+            // complete_task ended the run: answer the call so the history never ends on a dangling tool_use.
+            params.conversationMessages.push(BuildToolResultTurn([{
+                    toolCallId: guardrailCheckedStep.payloadToolCallId,
+                    toolName: this.nativeToolNameForCall(guardrailCheckedStep, guardrailCheckedStep.payloadToolCallId),
+                    content: 'Task complete.',
+                    isError: false
+                }], { turnAdded: this._promptTurnCount, messageType: 'action-result' }));
+        }
         else if (guardrailCheckedStep.step === 'Retry' && (guardrailCheckedStep.message || guardrailCheckedStep.errorMessage || guardrailCheckedStep.retryInstructions)) {
             params.conversationMessages.push({
                 role: 'user',
@@ -5685,6 +6183,10 @@ The context is now within limits. Please retry your request with the recovered c
         // Return the next step directly - execution handling is done in execute NextStep
         return guardrailCheckedStep;
     }
+    /** The tool name the model used for a call on this turn — `payload_change_request` when it cannot be found. */
+    nativeToolNameForCall(step, toolCallId) {
+        return step.nativeTurn?.toolCalls.find((c) => c.id === toolCallId)?.name ?? 'payload_change_request';
+    }
     /**
      * Executes a batch of artifact tool calls, recording each as its own
      * `Tool` AIAgentRunStep (a sibling of the Prompt step that requested them)
@@ -5979,10 +6481,10 @@ The context is now within limits. Please retry your request with the recovered c
                     throw new Error(`The '${BaseAgent.SummarizeRangePromptName}' system prompt is not present in this environment`);
                 }
                 const promptParams = new AIPromptParams();
+                Object.assign(promptParams, this.runPromptExecutionScope(params));
                 promptParams.prompt = prompt;
                 // Keys are the summarize-range.template.md contract ({{ lens }}, {{ messages }})
                 promptParams.data = { lens, messages: rangeText };
-                promptParams.contextUser = params.contextUser;
                 promptParams.agentId = params.agent.ID;
                 promptParams.UserID = ResolvePromptRunUserID({
                     UserID: params.userId,
@@ -6412,68 +6914,542 @@ The context is now within limits. Please retry your request with the recovered c
         };
         params.conversationMessages.push(message);
     }
+    /** At most this many decision calls run at once for one agent turn. */
+    static { this.DECISION_CONCURRENCY = 8; }
     /**
-     * Creates a chat message containing sub-agent execution results.
-     *
-     * @param {AgentSubAgentRequest} subAgent - The sub-agent that was executed
-     * @param {any} result - The result from sub-agent execution
-     * @returns {ChatMessage} A formatted message with sub-agent results
-     * @protected
+     * Runs `fn` over `items` with at most `limit` calls in flight, keeping results in input order.
+     * One call's failure never rejects the others: a call that throws is settled with `onError`'s
+     * result in its place.
      */
-    createSubAgentResultMessage(subAgent, result) {
-        return {
-            role: 'user',
-            content: this.formatSubAgentResultAsMarkdown(subAgent.name, result)
+    async runWithConcurrencyLimit(items, limit, fn, onError) {
+        const results = new Array(items.length);
+        let next = 0;
+        const worker = async () => {
+            while (next < items.length) {
+                const index = next++;
+                try {
+                    results[index] = await fn(items[index], index);
+                }
+                catch (error) {
+                    results[index] = onError(error, items[index], index);
+                }
+            }
         };
+        await Promise.all(Array.from({ length: Math.min(limit, items.length) }, () => worker()));
+        return results;
     }
     /**
-     * Gathers context data about the agent for use in prompt templates.
+     * Answers the decision requests from one agent turn, each logged as an `AIAgentRunStep`
+     * (StepType 'Decision'), with bounded concurrency. A failed request never fails the run: it
+     * becomes that request's `success: false`, which the agent reads on its next turn.
      *
-     * This method collects information about the agent's sub-agents and available
-     * actions, formatting them for injection into prompt templates. The data is
-     * structured to provide the LLM with comprehensive context about the agent's
-     * capabilities and hierarchical relationships.
+     * Two limits bound the turn. At most `decisionsMaxRequests` requests run (default
+     * {@link MAX_DECISION_REQUESTS_PER_TURN}); each request over that cap is not run and records no
+     * step, and its result says why. And the requests make at most `decisionsMaxCallsPerTurn`
+     * decision calls in total, counting every `forEachItemIn` item (default
+     * {@link MAX_DECISION_CALLS_PER_TURN}). That budget is handed out in request order before any
+     * call is made, so which calls run never depends on timing. A `forEachItemIn` request it cuts
+     * short asks its first items and reports the rest in `skippedCount`. A request it leaves no calls
+     * for is not run, records no step, and its result says why.
      *
-     * @param {MJAIAgentEntityExtended} agent - The agent to gather context for
-     * @param {UserInfo} [_contextUser] - Optional user context (reserved for future use)
-     * @param {any} [extraData] - Optional extra data to include in the context, if provided and keys conflict within the agent context data, the extraData will override the agent context data.
-     * @param {ActionChange[]} [actionChanges] - Optional runtime action modifications
+     * @since 2.132.0
+     */
+    async executeDecisionRequestsAsSteps(requests, finalPayload, agentTypePromptParams, params) {
+        const cap = this.decisionRequestCap(agentTypePromptParams);
+        const toRun = requests.slice(0, cap);
+        const overCap = requests.slice(cap);
+        if (overCap.length > 0) {
+            this.logStatus(`[Decisions] ${requests.length} decision requests on one turn — answering the first ${cap}, skipping ${overCap.length} (per-turn cap)`, true, params);
+        }
+        const budget = this.decisionCallBudget(agentTypePromptParams);
+        const allowances = this.allotDecisionCalls(toRun, finalPayload, agentTypePromptParams, budget, params);
+        const results = await this.runWithConcurrencyLimit(toRun, BaseAgent.DECISION_CONCURRENCY, async (req, index) => allowances[index].Wanted > 0 && allowances[index].Allowed === 0
+            ? this.overBudgetDecisionResult(req, index, budget)
+            : this.executeSingleDecisionRequestAsStep(req, finalPayload, agentTypePromptParams, params, allowances[index].Allowed), (error, req, index) => ({
+            id: this.decisionRequestId(req, index),
+            success: false,
+            error: `The decision request failed: ${error instanceof Error ? error.message : String(error)}`,
+        }));
+        const skipped = overCap.map((req, i) => ({
+            id: this.decisionRequestId(req, cap + i),
+            success: false,
+            error: `Not run: at most ${cap} decision requests are answered per turn. Ask again next turn if you still need it.`,
+        }));
+        return [...results, ...skipped];
+    }
+    /** The most decision requests one turn may run: `decisionsMaxRequests`, or {@link MAX_DECISION_REQUESTS_PER_TURN}. */
+    decisionRequestCap(agentTypePromptParams) {
+        return this.decisionLimit(agentTypePromptParams, 'decisionsMaxRequests', MAX_DECISION_REQUESTS_PER_TURN);
+    }
+    /**
+     * The most decision calls one turn's requests make in total, `forEachItemIn` items included:
+     * `decisionsMaxCallsPerTurn`, or {@link MAX_DECISION_CALLS_PER_TURN}.
+     */
+    decisionCallBudget(agentTypePromptParams) {
+        return this.decisionLimit(agentTypePromptParams, 'decisionsMaxCallsPerTurn', MAX_DECISION_CALLS_PER_TURN);
+    }
+    /** The most items one `forEachItemIn` request asks about: `decisionsMaxItems`, or its default. */
+    decisionMaxItems(agentTypePromptParams) {
+        return this.decisionLimit(agentTypePromptParams, 'decisionsMaxItems', DEFAULT_LOOP_AGENT_PROMPT_PARAMS.decisionsMaxItems);
+    }
+    /** A decision limit from the prompt params when it is a non-negative integer, or `fallback` when it is absent or anything else. */
+    decisionLimit(agentTypePromptParams, name, fallback) {
+        const configured = agentTypePromptParams?.[name];
+        return typeof configured === 'number' && Number.isInteger(configured) && configured >= 0 ? configured : fallback;
+    }
+    /**
+     * Hands out the turn's decision-call budget to its requests in order, before any of them runs.
+     * Each request gets the calls it wants while the budget lasts. The first one the budget cannot
+     * cover gets what is left, and the ones after it get none.
+     */
+    allotDecisionCalls(requests, finalPayload, agentTypePromptParams, budget, params) {
+        let remaining = budget;
+        const allowances = requests.map((request) => {
+            const wanted = this.decisionCallsWanted(request, finalPayload, agentTypePromptParams);
+            const allowed = Math.min(wanted, remaining);
+            remaining -= allowed;
+            return { Wanted: wanted, Allowed: allowed };
+        });
+        const cut = allowances.reduce((sum, allowance) => sum + allowance.Wanted - allowance.Allowed, 0);
+        if (cut > 0) {
+            this.logStatus(`[Decisions] The turn's decision requests want ${budget + cut} decision calls — making ${budget}, skipping ${cut} (per-turn call budget)`, true, params);
+        }
+        return allowances;
+    }
+    /**
+     * The decision calls a request makes with no budget: one, or one per `forEachItemIn` item up to
+     * `decisionsMaxItems`. A request that cannot make any, because it is not an object or its
+     * `forEachItemIn` is not an array, wants none. A request that fails before it asks, such as one
+     * with no valid question, still holds what its shape wants: the budget can then go unused, but
+     * it is never exceeded.
+     */
+    decisionCallsWanted(request, finalPayload, agentTypePromptParams) {
+        if (!request || typeof request !== 'object') {
+            return 0;
+        }
+        if (!request.forEachItemIn) {
+            return 1;
+        }
+        const target = typeof request.forEachItemIn === 'string' ? this.resolvePayloadPath(request.forEachItemIn, finalPayload) : undefined;
+        return Array.isArray(target) ? Math.min(target.length, this.decisionMaxItems(agentTypePromptParams)) : 0;
+    }
+    /**
+     * The result of a request the turn's decision-call budget left no calls for. It was not run.
+     * A budget of 0 turns decision calls off for the agent, so then asking again on a later turn
+     * cannot help, and the result does not invite it.
+     */
+    overBudgetDecisionResult(request, index, budget) {
+        const error = budget === 0
+            ? 'Not run: this agent\'s decision-call budget is 0 (decisionsMaxCallsPerTurn), so it makes no decision calls on any turn. Asking again will not help: carry on without the answer.'
+            : `Not run: one turn's decisions make at most ${budget} decision calls in total, counting each forEachItemIn item, and the requests before this one used them all. Ask again next turn if you still need it.`;
+        return { id: this.decisionRequestId(request, index), success: false, error };
+    }
+    /** A request's id for its result, or its position when the model sent no usable id. */
+    decisionRequestId(request, index) {
+        const id = request && typeof request === 'object' ? request.id : undefined;
+        return typeof id === 'string' && id.length > 0 ? id : `request ${index + 1}`;
+    }
+    /**
+     * Runs a `'Decision'` next step: an agent type's decision requests, answered with no LLM turn.
      *
-     * @returns {Promise<AgentContextData>} Structured context data for prompts
+     * Each request goes through the same path a loop turn's decisions take
+     * ({@link executeSingleDecisionRequestAsStep}), so it gets the same prompt default, state
+     * resolution and error handling, and is logged as a `Decision` run step. Where a loop turn's
+     * results go into the conversation, these come back to the agent type on the returned `'Retry'`
+     * (`decisionResults`), because it routes on them. So each answer keeps its whole distribution
+     * (`SummarizeDecisionAnswers`), which a path condition may read. A failed request is a result
+     * with `success: false`, never a failed run: what a failure means is the agent type's call.
      *
-     * @throws {Error} If there's an error accessing agent data
+     * @since 6.2.0
+     */
+    async executeDecisionStep(params, decision) {
+        const payload = decision.newPayload ?? decision.previousPayload;
+        const promptParams = decision.decisionPromptName ? { decisionPromptName: decision.decisionPromptName } : undefined;
+        const results = await this.runWithConcurrencyLimit(decision.decisions ?? [], BaseAgent.DECISION_CONCURRENCY, request => this.executeSingleDecisionRequestAsStep(request, payload, promptParams, params, Number.POSITIVE_INFINITY, SummarizeDecisionAnswers), (error, request, index) => ({
+            id: this.decisionRequestId(request, index),
+            success: false,
+            error: `The decision request failed: ${error instanceof Error ? error.message : String(error)}`,
+        }));
+        return { step: 'Retry', terminate: false, decisionResults: results, previousPayload: payload, newPayload: payload };
+    }
+    /**
+     * Answers one decision request, either once against its `state` or once per item of its
+     * `forEachItemIn` array, and records it as a Decision step. The request is unchecked model
+     * output, so any error finishes the step as failed rather than escaping: this never throws
+     * once the step exists.
      *
-     * @private
+     * @param callAllowance The most decision calls the request may make, from the turn's
+     * `decisionsMaxCallsPerTurn` budget. It caps a `forEachItemIn` request's items below
+     * `decisionsMaxItems`. A single-state request makes one call, and
+     * {@link executeDecisionRequestsAsSteps} never starts one the budget left without it.
+     * Unbounded by default.
+     * @param summarize how the typed answers are summarised for whoever reads them next; defaults
+     *                  to the loop turn's model-facing summary
+     * @since 2.132.0
      */
-    async gatherPromptTemplateData(agent, _contextUser, extraData, actionChanges, subAgentChanges) {
+    async executeSingleDecisionRequestAsStep(request, finalPayload, agentTypePromptParams, params, callAllowance = Number.POSITIVE_INFINITY, summarize = AgentDecisionService.SummarizeAnswers) {
+        const step = await this.createStepEntity({
+            stepType: 'Decision',
+            stepName: `Decision: ${request.id}`,
+            contextUser: params.contextUser,
+            inputData: { id: request.id, state: request.state, forEachItemIn: request.forEachItemIn, questions: request.questions },
+        });
         try {
-            const engine = AIEngine.Instance;
-            // Build (or reuse) the agent-invariant base catalog. This is process-wide cached on
-            // AIEngine and wiped on Agent/AgentAction/AgentRelationship/AgentType changes + reloads.
-            // It turns the per-step rebuild (sub-agent + action resolution, markdown, JSON.parse of
-            // agent-type params) into a once-per-agent cost; the common no-override step reuses it wholesale.
-            let catalog = engine.GetAgentBaseCatalog(agent.ID);
-            if (!catalog) {
-                catalog = this.buildAgentBaseCatalog(agent, engine);
-                engine.SetAgentBaseCatalog(agent.ID, catalog);
-            }
-            const isRoot = this._depth === 0;
-            // Sub-agents: reuse cached base unless runtime subAgentChanges apply (then clone + re-format).
-            let uniqueActiveSubAgents = catalog.uniqueActiveSubAgents;
-            let subAgentDetails = catalog.subAgentDetails;
-            let subAgentCount = catalog.subAgentCount;
-            if (subAgentChanges?.length) {
-                uniqueActiveSubAgents = this.applySubAgentChanges(catalog.uniqueActiveSubAgents, subAgentChanges, agent.ID, isRoot, engine);
-                subAgentCount = uniqueActiveSubAgents.length;
-                subAgentDetails = this.formatSubAgentDetails(uniqueActiveSubAgents);
-            }
-            // Actions: reuse cached active set unless runtime actionChanges apply (then clone + re-format).
-            //
-            // FAST-PATH SHARING CONTRACT: on the no-override path, `activeActions` (and therefore
-            // `_effectiveActions`) and `uniqueActiveSubAgents` above are the SAME array references
-            // held by the process-wide AIEngine catalog cache. Downstream consumers MUST treat them
-            // as read-only — they are only ever read (`.find`/`.map`/`.length`/`.some`), never mutated
-            // in place. On the override path a fresh array is built via filter/applyActionChanges, so
+            const mapping = request.questions && typeof request.questions === 'object'
+                ? AgentDecisionService.ToDecisionQuestions(request.questions)
+                : { Questions: {}, Invalid: [] };
+            if (Object.keys(mapping.Questions).length === 0) {
+                const error = mapping.Invalid.length > 0
+                    ? `No valid questions: ${mapping.Invalid.join('; ')}`
+                    : 'At least one question is required';
+                return await this.finishDecisionStep(step, request, { Error: error });
+            }
+            if (mapping.Invalid.length > 0) {
+                this.logStatus(`[Decisions] "${request.id}": dropped ${mapping.Invalid.length} invalid question(s): ${mapping.Invalid.join('; ')}`, true, params);
+            }
+            const ask = this.decisionAsker(mapping.Questions, agentTypePromptParams, params);
+            const outcome = request.forEachItemIn
+                ? await this.askForEachItem(request, finalPayload, agentTypePromptParams, callAllowance, params, step, ask, summarize)
+                : await this.askOnce(request, finalPayload, step, ask, summarize);
+            return await this.finishDecisionStep(step, request, outcome, mapping.Invalid);
+        }
+        catch (error) {
+            const message = `The decision request failed: ${error instanceof Error ? error.message : String(error)}`;
+            return this.finishDecisionStep(step, request, { Error: message });
+        }
+    }
+    /** Asks the request's questions about one state, with the configured decision prompt. */
+    decisionAsker(questions, agentTypePromptParams, params) {
+        const promptName = typeof agentTypePromptParams?.decisionPromptName === 'string'
+            ? agentTypePromptParams.decisionPromptName
+            : AgentDecisionService.DEFAULT_PROMPT_NAME;
+        return (state) => this._agentDecisionService.Ask({
+            State: state,
+            Questions: questions,
+            ContextUser: params.contextUser,
+            AgentID: params.agent?.ID ?? this._agentRun?.AgentID,
+            PromptName: promptName,
+            CancellationToken: params.cancellationToken,
+            ExecutionScope: this.runPromptExecutionScope(params),
+        });
+    }
+    /** Asks the questions once, against the request's state. */
+    async askOnce(request, finalPayload, step, ask, summarize) {
+        const state = this.resolveDecisionState(request.state, finalPayload);
+        if ('Error' in state) {
+            return state;
+        }
+        const result = await ask(state.State);
+        this.attachDecisionPromptRun(step, result);
+        if (!result.success) {
+            return { Error: result.errorMessage || 'Decision evaluation failed' };
+        }
+        return { Answers: summarize(result.Answers), Results: [result] };
+    }
+    /**
+     * Asks the same questions of each item of a payload array, up to `decisionsMaxItems` and the
+     * request's share of the turn's call budget. Each item's call is its own child Decision step of
+     * the request's step, carrying that call's prompt run, as each iteration of a ForEach is a child
+     * step of its loop step.
+     */
+    async askForEachItem(request, finalPayload, agentTypePromptParams, callAllowance, params, step, ask, summarize) {
+        const target = this.resolvePayloadPath(request.forEachItemIn ?? '', finalPayload);
+        if (!Array.isArray(target)) {
+            return { Error: `forEachItemIn target "${request.forEachItemIn}" is not an array` };
+        }
+        const maxItems = this.decisionMaxItems(agentTypePromptParams);
+        const limit = Math.min(maxItems, callAllowance);
+        const items = target.slice(0, limit);
+        const skippedCount = target.length > limit ? target.length - limit : undefined;
+        if (skippedCount) {
+            const why = limit < maxItems ? "the turn's decision-call budget" : 'decisionsMaxItems';
+            this.logStatus(`[Decisions] "${request.forEachItemIn}" has ${target.length} items; asking the first ${limit} (${skippedCount} skipped: ${why})`, true, params);
+        }
+        const results = await this.runWithConcurrencyLimit(items, BaseAgent.DECISION_CONCURRENCY, (item, index) => this.askItemAsStep(request, item, index, step, ask, params), (error) => ({ success: false, errorMessage: error instanceof Error ? error.message : String(error), Answers: {} }));
+        const failedIndex = results.findIndex(r => !r.success);
+        if (failedIndex >= 0) {
+            return { Error: `Item ${failedIndex}: ${results[failedIndex].errorMessage || 'decision evaluation failed'}` };
+        }
+        return { Answers: results.map(r => summarize(r.Answers)), Results: results, SkippedCount: skippedCount };
+    }
+    /** Asks about one item of a `forEachItemIn` request, recorded as a child step of the request's step. */
+    async askItemAsStep(request, item, index, parentStep, ask, params) {
+        const itemStep = await this.createStepEntity({
+            stepType: 'Decision',
+            stepName: `Decision: ${request.id} (item ${index})`,
+            contextUser: params.contextUser,
+            inputData: { id: request.id, item: index },
+            parentId: parentStep.ID,
+        });
+        let result;
+        try {
+            result = await ask(this.decisionStateText(item));
+        }
+        catch (error) {
+            result = { success: false, errorMessage: `The decision call failed: ${error instanceof Error ? error.message : String(error)}`, Answers: {} };
+        }
+        this.attachDecisionPromptRun(itemStep, result);
+        await this.finalizeStepEntity(itemStep, result.success, result.success ? undefined : result.errorMessage, result.success ? { answers: AgentDecisionService.SummarizeAnswers(result.Answers) } : undefined);
+        return result;
+    }
+    /**
+     * Links a decision call's prompt run to its step, as the Prompt step links its own, so the run's
+     * cost and token totals and its `MaxCostPerRun` / `MaxTokensPerRun` checks count the call.
+     */
+    attachDecisionPromptRun(step, result) {
+        if (result.promptRun?.ID) {
+            step.TargetLogID = result.promptRun.ID;
+            step.PromptRun = result.promptRun; // transient related object (not a persisted field)
+        }
+    }
+    /**
+     * Links the prompt run of a decision call the run stopped waiting for (a timeout or a cancellation)
+     * to its step, once the call settles. `AIDecisionRunner` writes the prompt run before it calls the
+     * model, so a stopped call still has one. The link keeps that row on the run's trace, and counts its
+     * usage in the run's cost and token totals when it settles before the run ends, as
+     * {@link attachDecisionPromptRun} does on time. The step may already be finalized, so the link is
+     * saved on its own. Never throws, and a call that never settles links nothing.
+     */
+    linkLateDecisionPromptRun(step, late) {
+        if (!step) {
+            return;
+        }
+        late.then(result => {
+            const promptRunID = result?.promptRun?.ID;
+            if (!result || !promptRunID || step.TargetLogID === promptRunID) {
+                return;
+            }
+            this.attachDecisionPromptRun(step, result);
+            this.queueStepSave(step, (s) => { s.TargetLogID = promptRunID; });
+        }).catch(error => {
+            LogError(`Could not link a stopped decision call's prompt run to its step: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    }
+    /**
+     * A literal state, or a value read from the payload: the whole payload for `payload`, one value
+     * for a `payload.` path.
+     */
+    resolveDecisionState(state, finalPayload) {
+        if (typeof state !== 'string') {
+            return { Error: 'Either state or forEachItemIn is required' };
+        }
+        if (state.trim() !== 'payload' && !state.startsWith('payload.')) {
+            return { State: state };
+        }
+        const value = this.resolvePayloadPath(state, finalPayload);
+        return value === undefined ? { Error: `Path "${state}" not found in payload` } : { State: this.decisionStateText(value) };
+    }
+    /** Reads a `payload.`-prefixed dotted path (or `payload` itself) from the payload. */
+    resolvePayloadPath(path, finalPayload) {
+        const trimmed = path.trim();
+        if (trimmed === 'payload') {
+            return finalPayload;
+        }
+        return _.get(finalPayload, trimmed.startsWith('payload.') ? trimmed.substring('payload.'.length) : trimmed);
+    }
+    /** Strings pass through; anything else becomes indented JSON. */
+    decisionStateText(value) {
+        return typeof value === 'string' ? value : (value !== null && typeof value === 'object' ? JSON.stringify(value, undefined, 1) : String(value ?? ''));
+    }
+    /** Finalizes the Decision step and builds the result the agent reads next turn. */
+    async finishDecisionStep(step, request, outcome, droppedQuestions = []) {
+        if ('Error' in outcome) {
+            await this.finalizeStepEntity(step, false, outcome.Error, { error: outcome.Error });
+            return { id: request.id, success: false, error: outcome.Error };
+        }
+        const first = outcome.Results[0];
+        await this.finalizeStepEntity(step, true, undefined, {
+            answers: outcome.Answers,
+            skippedCount: outcome.SkippedCount,
+            executionTimeMS: outcome.Results.reduce((sum, r) => sum + (r.executionTimeMS ?? 0), 0),
+            tokensUsed: outcome.Results.reduce((sum, r) => sum + (r.tokensUsed ?? 0), 0),
+            model: first?.DecisionResult?.ResolvedModel ?? first?.modelInfo?.modelName,
+            promptRunId: first?.promptRun?.ID,
+            driverClass: first?.DriverClass,
+            ...(droppedQuestions.length > 0 && { droppedQuestions }),
+        });
+        return { id: request.id, success: true, answers: outcome.Answers, skippedCount: outcome.SkippedCount };
+    }
+    /**
+     * Answers the decision requests a prompt returned, or holds them when the step that carries
+     * them can end the run, because then no turn would read their answers. Held requests run before
+     * the next prompt ({@link runHeldDecisions}), or are skipped if the run ends first
+     * ({@link skipHeldDecisions}). Skips them all, unasked, while the master switch is off
+     * ({@link DecisionsEnabled}) or the agent's `decisions` response field is.
+     */
+    async processTurnDecisions(decisions, nextStep, finalPayload, agentTypePromptParams, params) {
+        if (!this.DecisionsEnabled(agentTypePromptParams)) {
+            this.logStatus(`[Decisions] LLM requested decisions but decision-model use is off for this agent (decisionsEnabled is not true) — skipped`, true, params);
+            return;
+        }
+        const responseTypeRules = agentTypePromptParams?.includeResponseTypeDefinition;
+        if (responseTypeRules?.decisions === false) {
+            this.logStatus(`[Decisions] LLM requested decisions but feature is disabled (includeResponseTypeDefinition.decisions=false) — skipped`, true, params);
+            return;
+        }
+        if (!Array.isArray(decisions)) {
+            this.injectDecisionResultsMessage(params, [{ id: 'decisions', success: false, error: '"decisions" must be an array of decision requests' }]);
+            return;
+        }
+        const ids = decisions.map((d, i) => this.decisionRequestId(d, i)).join(', ');
+        const holdReason = this.decisionsHoldReason(nextStep);
+        if (holdReason) {
+            this._heldDecisions = { Requests: decisions, Payload: finalPayload, PromptParams: agentTypePromptParams, Reason: holdReason };
+            this.logStatus(`[Decisions] Holding ${decisions.length} decision request(s) (${ids}) until the step has run: ${holdReason}`, true, params);
+            return;
+        }
+        this.logStatus(`[Decisions] LLM requested ${decisions.length} decision request(s): ${ids}`, true, params);
+        const decisionResults = await this.executeDecisionRequestsAsSteps(decisions, finalPayload, agentTypePromptParams, params);
+        this.injectDecisionResultsMessage(params, decisionResults);
+    }
+    /**
+     * Why the decisions sent with this step would be paid for and never read, or `undefined` when
+     * the next turn reads them. Three ways a step's own outcome ends the run: a passing finishIf gate
+     * (only an Actions step or a single sub-agent is gated), a sub-agent's `terminateAfter`, and
+     * client tools sent with `taskComplete`, which end the run once the tools return. Every other
+     * step, including client tools without `taskComplete`, goes on to a prompt that reads them.
+     */
+    decisionsHoldReason(step) {
+        const isSingleSubAgent = step.step === 'Sub-Agent' && !!step.subAgent && !step.subAgents?.length;
+        if (step.finishIf && (step.step === 'Actions' || isSingleSubAgent) && this.finishIfActs()) {
+            return `the ${step.step} step carries a finishIf gate, and a passing gate ends the run`;
+        }
+        if (step.step === 'Sub-Agent' && this.getRequestedSubAgents(step).some(r => r.terminateAfter === true)) {
+            return 'the Sub-Agent step has terminateAfter, which ends the run after it';
+        }
+        if (step.step === 'ClientTools' && step.terminate === true) {
+            return 'the client tools were sent with taskComplete, which ends the run once they return';
+        }
+        return undefined;
+    }
+    /**
+     * Runs the decision requests a prompt held back, now that the step that carried them has run
+     * without ending the run, so the prompt about to run reads their answers.
+     */
+    async runHeldDecisions(params) {
+        const held = this._heldDecisions;
+        if (!held) {
+            return;
+        }
+        this._heldDecisions = undefined;
+        this.logStatus(`[Decisions] The run continues, so answering ${held.Requests.length} held decision request(s)`, true, params);
+        const results = await this.executeDecisionRequestsAsSteps(held.Requests, held.Payload, held.PromptParams, params);
+        this.injectDecisionResultsMessage(params, results);
+    }
+    /**
+     * Skips the decision requests a prompt held back, because the run ended before they could be
+     * asked: the step that carried them ended it, or it was cancelled, or an error was thrown out of
+     * the step loop. Called from the loop's terminate branch and from `Execute()`'s `finally`, so
+     * every way out logs them. The held state is cleared before the log line, so the second call on
+     * the terminate path logs nothing and each held request is logged exactly once.
+     *
+     * @param runEnd How the run ended, as a clause for the log line.
+     */
+    skipHeldDecisions(params, runEnd) {
+        const held = this._heldDecisions;
+        if (!held) {
+            return;
+        }
+        this._heldDecisions = undefined;
+        const ids = held.Requests.map((d, i) => this.decisionRequestId(d, i)).join(', ');
+        this.logStatus(`[Decisions] Skipped ${held.Requests.length} held decision request(s) (${ids}) without asking them: ${runEnd}, so no turn would read the answers (they were held because ${held.Reason})`, false, params);
+    }
+    /** How the run ended, as a clause for held decision requests that a cancellation or an error left unasked. */
+    runEndForHeldDecisions() {
+        switch (this.deriveRunOutcome()) {
+            case 'cancelled':
+                return 'the run was cancelled before they were asked';
+            case 'failure':
+                return 'the run failed before they were asked';
+            default:
+                return 'the run ended before they were asked';
+        }
+    }
+    /**
+     * Injects decision results into the conversation as one tool-result message for the next turn.
+     *
+     * @since 2.132.0
+     */
+    injectDecisionResultsMessage(params, results) {
+        if (!results || results.length === 0)
+            return;
+        const message = {
+            role: 'user',
+            content: `Decision results:\n${JSON.stringify(results)}`,
+            metadata: {
+                turnAdded: this._promptTurnCount,
+                messageType: 'tool-result',
+                expirationTurns: 3,
+                expirationMode: 'Compact',
+                compactMode: 'First N Chars',
+                compactLength: 500,
+                compactPromptId: '',
+            },
+        };
+        params.conversationMessages.push(message);
+    }
+    /**
+     * Creates a chat message containing sub-agent execution results.
+     *
+     * @param {AgentSubAgentRequest} subAgent - The sub-agent that was executed
+     * @param {any} result - The result from sub-agent execution
+     * @returns {ChatMessage} A formatted message with sub-agent results
+     * @protected
+     */
+    createSubAgentResultMessage(subAgent, result) {
+        return {
+            role: 'user',
+            content: this.formatSubAgentResultAsMarkdown(subAgent.name, result)
+        };
+    }
+    /**
+     * Gathers context data about the agent for use in prompt templates.
+     *
+     * This method collects information about the agent's sub-agents and available
+     * actions, formatting them for injection into prompt templates. The data is
+     * structured to provide the LLM with comprehensive context about the agent's
+     * capabilities and hierarchical relationships.
+     *
+     * @param {MJAIAgentEntityExtended} agent - The agent to gather context for
+     * @param {UserInfo} [_contextUser] - Optional user context (reserved for future use)
+     * @param {any} [extraData] - Optional extra data to include in the context, if provided and keys conflict within the agent context data, the extraData will override the agent context data.
+     * @param {ActionChange[]} [actionChanges] - Optional runtime action modifications
+     *
+     * @returns {Promise<AgentContextData>} Structured context data for prompts
+     *
+     * @throws {Error} If there's an error accessing agent data
+     *
+     * @private
+     */
+    async gatherPromptTemplateData(agent, _contextUser, extraData, actionChanges, subAgentChanges) {
+        try {
+            const engine = AIEngine.Instance;
+            // Build (or reuse) the agent-invariant base catalog. This is process-wide cached on
+            // AIEngine and wiped on Agent/AgentAction/AgentRelationship/AgentType changes + reloads.
+            // It turns the per-step rebuild (sub-agent + action resolution, markdown, JSON.parse of
+            // agent-type params) into a once-per-agent cost; the common no-override step reuses it wholesale.
+            let catalog = engine.GetAgentBaseCatalog(agent.ID);
+            if (!catalog) {
+                catalog = this.buildAgentBaseCatalog(agent, engine);
+                engine.SetAgentBaseCatalog(agent.ID, catalog);
+            }
+            const isRoot = this._depth === 0;
+            // Sub-agents: reuse cached base unless runtime subAgentChanges apply (then clone + re-format).
+            let uniqueActiveSubAgents = catalog.uniqueActiveSubAgents;
+            let subAgentDetails = catalog.subAgentDetails;
+            let subAgentCount = catalog.subAgentCount;
+            if (subAgentChanges?.length) {
+                uniqueActiveSubAgents = this.applySubAgentChanges(catalog.uniqueActiveSubAgents, subAgentChanges, agent.ID, isRoot, engine);
+                subAgentCount = uniqueActiveSubAgents.length;
+                subAgentDetails = this.formatSubAgentDetails(uniqueActiveSubAgents);
+            }
+            // Actions: reuse cached active set unless runtime actionChanges apply (then clone + re-format).
+            //
+            // FAST-PATH SHARING CONTRACT: on the no-override path, `activeActions` (and therefore
+            // `_effectiveActions`) and `uniqueActiveSubAgents` above are the SAME array references
+            // held by the process-wide AIEngine catalog cache. Downstream consumers MUST treat them
+            // as read-only — they are only ever read (`.find`/`.map`/`.length`/`.some`), never mutated
+            // in place. On the override path a fresh array is built via filter/applyActionChanges, so
             // the cached arrays are never the mutated ones. Keeping the references (vs. copying) avoids
             // a per-step allocation; if a future consumer needs to mutate, it must `.slice()` first.
             let activeActions = catalog.activeActions;
@@ -6510,10 +7486,8 @@ The context is now within limits. Please retry your request with the recovered c
                 // and removes any cache-poisoning foot-gun should a future consumer write to it.
                 agentTypePromptParams = { ...catalog.baseAgentTypePromptParams };
             }
-            // Build client tool details for the prompt (per-run; depends on extraData)
-            const clientToolDetails = this.buildClientToolPromptSection(agent, extraData);
-            // Build app context section if provided in extraData
-            const appContext = this.buildAppContextSection(extraData);
+            // Store for the finishIf gate, which runs after this prompt in executeActionsStep / executeNextStep
+            this._agentTypePromptParams = agentTypePromptParams;
             // Skill catalog (name + description only — progressive disclosure). This is the
             // SELF-ACTIVATION surface, so it uses the double-gated auto set: empty unless the
             // agent's SkillActivationMode is 'Auto', and containing only skills whose own
@@ -6523,7 +7497,20 @@ The context is now within limits. Please retry your request with the recovered c
             // is never even offered a skill the user isn't entitled to — the permission
             // boundary is enforced at the catalog, not just at activation.
             const availableSkills = await this.availableSkills(engine.GetAutoActivatableSkillsForAgent(agent, _contextUser), 'catalog', agent, _contextUser);
-            const skillsCatalog = this.formatSkillsCatalog(availableSkills);
+            // Catalog narrowing (plan Task 3.7), off unless decisionsEnabled is true and maxActionsInPrompt /
+            // maxSubAgentsInPrompt is positive and the list is longer. It narrows what the prompt SHOWS, once per run:
+            // _effectiveActions / _effectiveSubAgents above stay whole, so validation forbids nothing.
+            // Skills are narrowed here, after the filterAvailableSkills policy, never inside it: the
+            // decision judges only skills the policy offers, and an override that skips `super` keeps it.
+            // The counts stay whole: they are what the model can call, and a narrowed list says what it hides.
+            await this.ensureCatalogNarrowing(agent, _contextUser, agentTypePromptParams, activeActions, uniqueActiveSubAgents, availableSkills);
+            actionDetails = this.narrowedCatalogSection('action', activeActions, actionDetails, shown => this.formatActionDetails(shown));
+            subAgentDetails = this.narrowedCatalogSection('agent', uniqueActiveSubAgents, subAgentDetails, shown => this.formatSubAgentDetails(shown));
+            const skillsCatalog = this.narrowedCatalogSection('skill', availableSkills, this.formatSkillsCatalog(availableSkills), shown => this.formatSkillsCatalog(shown));
+            // Build client tool details for the prompt (per-run; depends on extraData)
+            const clientToolDetails = this.buildClientToolPromptSection(agent, extraData);
+            // Build app context section if provided in extraData
+            const appContext = this.buildAppContextSection(extraData);
             const contextData = {
                 agentName: agent.Name,
                 agentDescription: agent.Description,
@@ -6567,6 +7554,231 @@ The context is now within limits. Please retry your request with the recovered c
             throw new Error(`Error gathering context data: ${error.message}`);
         }
     }
+    /**
+     * Narrows the catalog once per run, on its first prompt (plan Task 3.7), and caches the result for
+     * every later step. With narrowing off, or the master switch ({@link DecisionsEnabled}) off, it
+     * asks nothing and records nothing, so the prompt describes the whole catalog. Never throws: any
+     * failure leaves the full catalog in place. It narrows the prose catalog only:
+     * {@link applyNativeTools} still declares every action and sub-agent.
+     */
+    async ensureCatalogNarrowing(agent, contextUser, promptParams, actions, subAgents, skills) {
+        if (this._catalogNarrowing) {
+            return;
+        }
+        // Set first, so a failure below is cached as "hide nothing" rather than retried every step.
+        this._catalogNarrowing = NoCatalogNarrowing();
+        if (!this.DecisionsEnabled(promptParams)) {
+            return;
+        }
+        const limits = this.reachableCatalogNarrowingLimits(agent, promptParams, actions);
+        if (limits.Actions === 0 && limits.SubAgents === 0 && limits.Skills === 0) {
+            return;
+        }
+        try {
+            const candidates = this.catalogNarrowingCandidates(agent, actions, subAgents, skills);
+            const asked = CatalogNarrowingCandidatesToAsk(candidates, limits);
+            if (asked.length > 0) {
+                this._catalogNarrowing = await this.narrowCatalog(agent, contextUser, promptParams, candidates, asked, limits);
+            }
+        }
+        catch (error) {
+            this.warnCatalogNarrowing(agent, error instanceof Error ? error.message : String(error));
+        }
+    }
+    /**
+     * The run's limits, with actions left whole when the agent lacks Find Candidate Actions: a hidden
+     * action would then be unreachable. That case is logged as a warning when it keeps a long action
+     * list whole, since the agent asked for narrowing and did not get it.
+     */
+    reachableCatalogNarrowingLimits(agent, promptParams, actions) {
+        const configured = ResolveCatalogNarrowingLimits(promptParams);
+        const limits = ReachableCatalogNarrowingLimits(configured, actions.map(a => a.Name));
+        if (limits.Actions !== configured.Actions && IsCatalogListNarrowed(configured.Actions, actions.length)) {
+            LogErrorEx({
+                message: `Catalog narrowing for '${agent.Name}' shows every action: the agent has no ${CATALOG_NARROWING_FIND_ACTIONS} action, so a hidden action could not be found`,
+                severity: 'warning',
+                category: 'CatalogNarrowing',
+            });
+        }
+        return limits;
+    }
+    /**
+     * Every item of the three lists as a narrowing candidate. An action or sub-agent with
+     * `MinExecutionsPerRun` set, and the Find Candidate tools, are pinned: always shown.
+     */
+    catalogNarrowingCandidates(agent, actions, subAgents, skills) {
+        const requiredActionIDs = AIEngine.Instance.AgentActions
+            .filter(aa => UUIDsEqual(aa.AgentID, agent.ID) && aa.Status === 'Active' && (aa.MinExecutionsPerRun ?? 0) > 0)
+            .map(aa => aa.ActionID);
+        const candidate = (kind, item, pinned) => ({ Kind: kind, ID: item.ID, Name: item.Name, Description: item.Description ?? '', Pinned: pinned });
+        return [
+            ...actions.map(a => candidate('action', a, IsAlwaysShownAction(a.Name) || requiredActionIDs.some(id => UUIDsEqual(id, a.ID)))),
+            ...subAgents.filter(s => !!s).map(s => candidate('agent', s, (s.MinExecutionsPerRun ?? 0) > 0)),
+            ...skills.map(s => candidate('skill', s, false)),
+        ];
+    }
+    /**
+     * Asks the one decision, records it as the `Catalog narrowing` step, and returns what to hide.
+     * Any failure is logged as a warning and hides nothing, so the prompt shows the full catalog.
+     */
+    async narrowCatalog(agent, contextUser, promptParams, candidates, asked, limits) {
+        if (!this._openingRequest || !contextUser) {
+            this.warnCatalogNarrowing(agent, contextUser
+                ? 'the run has no user message to judge the catalog against'
+                : 'the run has no context user');
+            return NoCatalogNarrowing();
+        }
+        const promptName = typeof promptParams.decisionPromptName === 'string'
+            ? promptParams.decisionPromptName
+            : AgentDecisionService.DEFAULT_PROMPT_NAME;
+        const step = await this.startCatalogNarrowingStep(contextUser, promptName, asked, limits);
+        const result = await this.askCatalogNarrowing(agent, contextUser, BuildCatalogNarrowingQuestions(asked), promptName, step);
+        const outcome = result.success ? SelectCatalogNarrowing(candidates, asked, result.Answers, limits) : undefined;
+        if (!outcome) {
+            const reason = result.success ? 'an answer was missing or was not a probability' : (result.errorMessage || 'the decision call failed');
+            this.warnCatalogNarrowing(agent, reason);
+            await this.finishCatalogNarrowingStep(step, result, undefined, reason);
+            return NoCatalogNarrowing();
+        }
+        await this.finishCatalogNarrowingStep(step, result, outcome);
+        return outcome;
+    }
+    /**
+     * The one decision call, against the opening request. Never throws, and never waits longer than
+     * {@link CATALOG_NARROWING_TIMEOUT_MS} or past the run's cancellation: a throw, a timeout and a
+     * cancelled run each come back as a failed result. Stopping also aborts the call, and links the
+     * prompt run it still returns to `step` once it does ({@link linkLateDecisionPromptRun}).
+     */
+    async askCatalogNarrowing(agent, contextUser, questions, promptName, step) {
+        const failed = (errorMessage) => ({ success: false, errorMessage, Answers: {} });
+        const controller = new AbortController();
+        let stoppedResult;
+        const stopped = new Promise(resolve => controller.signal.addEventListener('abort', () => {
+            stoppedResult = failed(String(controller.signal.reason));
+            resolve(stoppedResult);
+        }, { once: true }));
+        const runToken = this._executeParams?.cancellationToken;
+        const relayRunAbort = () => controller.abort('the run was cancelled');
+        if (runToken?.aborted) {
+            relayRunAbort();
+        }
+        else {
+            runToken?.addEventListener('abort', relayRunAbort, { once: true });
+        }
+        const timeoutMS = BaseAgent.CATALOG_NARROWING_TIMEOUT_MS;
+        const timer = setTimeout(() => controller.abort(`the decision call timed out after ${timeoutMS}ms`), timeoutMS);
+        try {
+            const ask = this._agentDecisionService.Ask({
+                State: this._openingRequest,
+                Questions: questions,
+                ContextUser: contextUser,
+                AgentID: agent.ID,
+                PromptName: promptName,
+                CancellationToken: controller.signal,
+                ExecutionScope: this._runExecutionScope,
+            });
+            const result = await Promise.race([ask, stopped]);
+            if (result === stoppedResult) {
+                this.linkLateDecisionPromptRun(step, ask);
+            }
+            return result;
+        }
+        catch (error) {
+            return failed(error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            clearTimeout(timer);
+            runToken?.removeEventListener('abort', relayRunAbort);
+        }
+    }
+    /** Opens the `Catalog narrowing` Decision step with the decision's inputs. Without a run there is no step. */
+    async startCatalogNarrowingStep(contextUser, promptName, asked, limits) {
+        if (!this._agentRun) {
+            return undefined;
+        }
+        const count = (kind) => asked.filter(c => c.Kind === kind).length;
+        try {
+            return await this.createStepEntity({
+                stepType: 'Decision',
+                stepName: 'Catalog narrowing',
+                contextUser,
+                inputData: {
+                    request: this._openingRequest,
+                    promptName,
+                    limits: { actions: limits.Actions, subAgents: limits.SubAgents, skills: limits.Skills },
+                    asked: { actions: count('action'), subAgents: count('agent'), skills: count('skill') },
+                },
+            });
+        }
+        catch (error) {
+            LogError(`Could not record the catalog narrowing step: ${error instanceof Error ? error.message : String(error)}`);
+            return undefined;
+        }
+    }
+    /** Finalizes the `Catalog narrowing` step: each narrowed list's counts, kept names and probabilities, or why it failed open. */
+    async finishCatalogNarrowingStep(step, result, outcome, reason) {
+        if (!step) {
+            return;
+        }
+        // Like every decision call, it counts toward the run's cost and tokens through its step
+        this.attachDecisionPromptRun(step, result);
+        const usage = {
+            executionTimeMS: result.executionTimeMS,
+            tokensUsed: result.tokensUsed,
+            model: result.DecisionResult?.ResolvedModel ?? result.modelInfo?.modelName,
+            promptRunId: result.promptRun?.ID,
+        };
+        if (!outcome) {
+            await this.finalizeStepEntity(step, false, reason, { failedOpen: true, reason, ...usage });
+            return;
+        }
+        const lists = {};
+        const stepKeys = { action: 'actions', agent: 'subAgents', skill: 'skills' };
+        for (const kind of ['action', 'agent', 'skill']) {
+            const list = outcome.Lists[kind];
+            if (list) {
+                lists[stepKeys[kind]] = { total: list.Total, limit: list.Limit, shown: list.Kept.length, kept: list.Kept, pinned: list.Pinned, probabilities: list.Probabilities };
+            }
+        }
+        await this.finalizeStepEntity(step, true, undefined, { ...lists, ...usage });
+    }
+    /** Logs that catalog narrowing failed open. */
+    warnCatalogNarrowing(agent, reason) {
+        LogErrorEx({
+            message: `Catalog narrowing for '${agent.Name}' failed, so the full catalog is shown: ${reason}`,
+            severity: 'warning',
+            category: 'CatalogNarrowing',
+        });
+    }
+    /** The items of one list the prompt shows. Returns `items` itself when the run's narrowing hides none of them. */
+    hideNarrowedOut(kind, items) {
+        return ApplyCatalogNarrowing(items, this._catalogNarrowing?.Hidden[kind]);
+    }
+    /**
+     * One catalog section as the prompt shows it: `full` when the run's narrowing hides none of
+     * `items`, otherwise a {@link CatalogNarrowingNote} saying how many are hidden and how to reach
+     * them, then the items still shown. A hidden item can still be called. Fails OPEN, unlike the
+     * skill policy: an error shows `full` and logs a warning.
+     */
+    narrowedCatalogSection(kind, items, full, format) {
+        try {
+            const shown = this.hideNarrowedOut(kind, items);
+            if (shown === items) {
+                return full;
+            }
+            const shownSet = new Set(shown);
+            const hiddenNames = items.filter(item => !shownSet.has(item)).map(item => item.Name);
+            return `${CatalogNarrowingNote(kind, hiddenNames)}\n\n${format(shown)}`;
+        }
+        catch (error) {
+            LogErrorEx({
+                message: `Catalog narrowing could not narrow the ${kind} list, so all of it is shown: ${error instanceof Error ? error.message : String(error)}`,
+                severity: 'warning',
+                category: 'CatalogNarrowing',
+            });
+            return full;
+        }
+    }
     /**
      * Builds the agent-invariant {@link AgentBaseCatalog} — the resolved sub-agents + actions and
      * their formatted markdown, plus the base agent-type prompt params. Computed once per agent and
@@ -6702,9 +7914,51 @@ The context is now within limits. Please retry your request with the recovered c
         // to distinguish between explicit user settings and schema defaults
         const explicitResponseType = runtimeOverrides?.includeResponseTypeDefinition ||
             agentParams.includeResponseTypeDefinition;
+        this.warnOnceOnUnknownFinishIfMode(merged.finishIfMode, agent);
         this.applyResponseTypeAutoAlignment(merged, explicitResponseType);
         return merged;
     }
+    /**
+     * The agent and value pairs {@link warnOnceOnUnknownFinishIfMode} has already reported. It is
+     * process-wide because the prompt params are merged again for every run of an agent, and on every
+     * turn that carries runtime overrides. One warning per agent and value is enough. A run request
+     * can set the value, so what this keeps is bounded: see {@link FinishIfModeWarnings}.
+     */
+    static { this.finishIfModeWarnings = new FinishIfModeWarnings(); }
+    /**
+     * Warns, once per agent and value, when the merged `finishIfMode` is set but is not a
+     * {@link FinishIfMode}. {@link ResolveFinishIfMode} treats such a value as `'off'`, so without
+     * this a typo such as `"On"` or `"true"` would turn the agent's gates off without a word. An
+     * absent value is the default, so it is not reported.
+     */
+    warnOnceOnUnknownFinishIfMode(value, agent) {
+        const warning = BaseAgent.finishIfModeWarnings.WarningFor(agent.ID, agent.Name, value);
+        if (warning) {
+            this.logError(warning, { agent, category: 'AgentConfiguration', severity: 'warning' });
+        }
+    }
+    /**
+     * The master switch for decision-model use by this agent: `decisionsEnabled` in its merged
+     * agent-type prompt params (type default < agent < the run's `data.__agentTypePromptParams`).
+     * Anything but `true` is off, the default.
+     *
+     * While it is off the agent never asks a decision model on its own. Each automatic use checks it
+     * before it asks, whatever its own setting says: inline `decisions` ({@link processTurnDecisions}),
+     * `finishIf` gates ({@link finishIfSettings}), decision discovery ({@link isDecisionDiscoveryOnFor}),
+     * the payload change check ({@link isPayloadFeedbackCheckOn}), catalog narrowing
+     * ({@link ensureCatalogNarrowing}) and the Memory Manager's note gate. And
+     * {@link applyResponseTypeAutoAlignment} keeps the `decisions` and `finishIf` docs and response
+     * fields out of the prompt. While it is on, each use keeps its own setting, and each is off by default.
+     *
+     * Explicit uses never read it: a Flow agent's Decision step ({@link executeDecisionStep}) runs because
+     * someone placed it, and the task-graph Decision step and the Run Decision action call
+     * {@link AgentDecisionService} directly. That is why the check sits at each automatic use, not in the service.
+     *
+     * @param promptParams - The merged agent-type prompt params.
+     */
+    DecisionsEnabled(promptParams) {
+        return promptParams?.decisionsEnabled === true;
+    }
     /**
      * Applies auto-alignment rules to includeResponseTypeDefinition based on other flags.
      *
@@ -6718,6 +7972,10 @@ The context is now within limits. Please retry your request with the recovered c
      * - includeCommandDocs → includeResponseTypeDefinition.commands
      * - includeForEachDocs → includeResponseTypeDefinition.forEach
      * - includeWhileDocs → includeResponseTypeDefinition.while
+     * - includeDecisionsDocs → includeResponseTypeDefinition.decisions
+     *
+     * While the master switch is off ({@link DecisionsEnabled}), the decisions and finishIf docs and
+     * response fields are off, even when set explicitly.
      *
      * @param params - The merged params object to modify in place
      * @param explicitResponseType - The explicitly set response type config from agent/runtime (not schema defaults)
@@ -6725,18 +7983,37 @@ The context is now within limits. Please retry your request with the recovered c
      * @since 2.132.0
      */
     applyResponseTypeAutoAlignment(params, explicitResponseType) {
+        // Align a copy: the object may be the caller's per-run override, which sub-agents inherit with the
+        // run's data. Writing into it would turn a key "explicit" for every later merge of that override.
+        if (IsPlainObject(params.includeResponseTypeDefinition)) {
+            params.includeResponseTypeDefinition = { ...params.includeResponseTypeDefinition };
+        }
         // Ensure includeResponseTypeDefinition is an object
-        if (!params.includeResponseTypeDefinition || typeof params.includeResponseTypeDefinition !== 'object') {
+        else if (!params.includeResponseTypeDefinition || typeof params.includeResponseTypeDefinition !== 'object') {
             params.includeResponseTypeDefinition = {
                 payload: true,
                 responseForms: true,
                 commands: true,
                 forEach: true,
                 while: true,
-                scratchpad: true
+                scratchpad: true,
+                decisions: true,
+                finishIf: true
             };
         }
         const responseType = params.includeResponseTypeDefinition;
+        const decisionsEnabled = this.DecisionsEnabled(params);
+        // finishIf gates are opt-in (`finishIfMode`), and need the master switch. While off, the model is
+        // not taught to write one, whatever includeFinishIfDocs says, so the response field below follows it off too.
+        if (!decisionsEnabled || ResolveFinishIfMode(params.finishIfMode) === 'off') {
+            params.includeFinishIfDocs = false;
+        }
+        // `decisions` is opt-in too (`includeDecisionsDocs: true`), and needs the master switch. Its docs and
+        // types add about 1,200 tokens to every turn, and on the Prompt Eval corpus no model used it
+        // (typed-decision plan, Task 4.7). Unset means off, so the response field below follows it off too.
+        if (!decisionsEnabled || params.includeDecisionsDocs !== true) {
+            params.includeDecisionsDocs = false;
+        }
         // Auto-alignment mappings: docs flag → response type property
         const alignmentMappings = [
             { docsFlag: 'includePayloadInPrompt', responseTypeKey: 'payload' },
@@ -6748,7 +8025,9 @@ The context is now within limits. Please retry your request with the recovered c
             { docsFlag: 'includeArtifactToolsDocs', responseTypeKey: 'artifactToolCalls' },
             { docsFlag: 'includeConversationToolsDocs', responseTypeKey: 'conversationToolCalls' },
             { docsFlag: 'includePipelineDocs', responseTypeKey: 'pipeline' },
-            { docsFlag: 'includeMemoryWritesDocs', responseTypeKey: 'memoryWrites' }
+            { docsFlag: 'includeMemoryWritesDocs', responseTypeKey: 'memoryWrites' },
+            { docsFlag: 'includeDecisionsDocs', responseTypeKey: 'decisions' },
+            { docsFlag: 'includeFinishIfDocs', responseTypeKey: 'finishIf' }
         ];
         for (const { docsFlag, responseTypeKey } of alignmentMappings) {
             // Check if the user explicitly set this response type property
@@ -6766,6 +8045,12 @@ The context is now within limits. Please retry your request with the recovered c
                 responseType[responseTypeKey] = true;
             }
         }
+        // With the master switch off, neither decision field is offered, even when set explicitly: the
+        // model must not be invited to ask for something the run would refuse.
+        if (!decisionsEnabled) {
+            responseType.decisions = false;
+            responseType.finishIf = false;
+        }
         // Capability gates align the OTHER way: default OFF, and the section appears only when the
         // gate is explicitly on. Running these through the loop above would invert their meaning —
         // that loop's `else` branch defaults an unset key to true, which is exactly what a gated
@@ -6811,12 +8096,346 @@ The context is now within limits. Please retry your request with the recovered c
             return {};
         }
     }
+    /**
+     * The finishIf settings of the current step, from its merged agent-type prompt params. A gate is
+     * evaluated when the master switch is on ({@link DecisionsEnabled}), `finishIfMode` is `shadow` or
+     * `on`, and `includeResponseTypeDefinition.finishIf` is not `false`; it ends the run only in `on`.
+     */
+    finishIfSettings() {
+        const promptParams = this._agentTypePromptParams;
+        const rules = promptParams?.includeResponseTypeDefinition;
+        const threshold = promptParams?.finishIfThreshold;
+        const mode = ResolveFinishIfMode(promptParams?.finishIfMode);
+        return {
+            Enabled: this.DecisionsEnabled(promptParams) && mode !== 'off' && rules?.finishIf !== false,
+            Mode: mode,
+            Threshold: typeof threshold === 'number' && threshold > 0 && threshold <= 1
+                ? threshold
+                : DEFAULT_LOOP_AGENT_PROMPT_PARAMS.finishIfThreshold,
+            PromptName: typeof promptParams?.decisionPromptName === 'string'
+                ? promptParams.decisionPromptName
+                : AgentDecisionService.DEFAULT_PROMPT_NAME,
+        };
+    }
+    /** Whether a passing finishIf gate ends the run: only in `on` mode. */
+    finishIfActs() {
+        const settings = this.finishIfSettings();
+        return settings.Enabled && settings.Mode === 'on';
+    }
+    /**
+     * Whether an evaluated gate ends the run. In shadow mode a passing gate is only logged: the
+     * outcome is already recorded on its `Finish check` step, and the model takes its next turn.
+     */
+    gateEndsRun(outcome, params) {
+        if (!outcome.Passed) {
+            return false;
+        }
+        if (!this.finishIfActs()) {
+            this.logStatus('[finishIf] Shadow mode: the gate passed, and the run continues as it would have', true, params);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Runs the finishIf gate after an Actions step, and returns the Success step when it passes.
+     * ForEach and While call executeActionsStep without a conversation message, and are never gated.
+     */
+    async finishAfterActions(params, decision, actionResults, actionSummaries, payload, parentStepId, addConversationMessage) {
+        const finishIf = decision.finishIf;
+        if (!finishIf || !addConversationMessage || !this.finishIfSettings().Enabled) {
+            return undefined;
+        }
+        // (In shadow mode the gate below is still evaluated and recorded; it just never ends the run.)
+        // `success` means only that the action did not throw; `result.Success` is its outcome.
+        if (!actionResults.every(r => r.success && r.result?.Success === true)) {
+            return undefined;
+        }
+        // AIDirectives are instructions for the model's next turn, which a passing gate would take away.
+        const withDirectives = actionSummaries.filter(a => (a.aiDirectives?.length ?? 0) > 0).map(a => a.actionName);
+        if (withDirectives.length > 0) {
+            this.logStatus(`[finishIf] Gate skipped: ${withDirectives.join(', ')} returned AIDirectives, which the model must see on its next turn`, false, params);
+            return undefined;
+        }
+        const state = CapFinishIfState(actionSummaries.map(FormatActionForFinishIf).join('\n\n'));
+        const outcome = await this.evaluateFinishIf(finishIf, state, params, decision, payload, parentStepId);
+        return this.gateEndsRun(outcome, params)
+            ? { ...this.finishIfSuccessStep(finishIf, decision, payload), priorStepResult: actionSummaries }
+            : undefined;
+    }
+    /**
+     * Runs the finishIf gate after a Sub-Agent step that succeeded without terminating, and returns
+     * the step with `terminate: true` when it passes, as `terminateAfter` would.
+     */
+    async finishAfterSubAgent(params, decision, result) {
+        const finishIf = decision.finishIf;
+        if (!finishIf || result.terminate || result.step !== 'Success' || !this.finishIfSettings().Enabled) {
+            return undefined;
+        }
+        const outcome = await this.evaluateFinishIf(finishIf, FormatSubAgentForFinishIf(result), params, decision, result.newPayload);
+        return this.gateEndsRun(outcome, params) ? { ...result, terminate: true, message: finishIf.message } : undefined;
+    }
+    /**
+     * Asks the finishIf questions about the step's results, then checks that the normal Success
+     * validation would allow the run to end. Records the check as a `Finish check` Decision step.
+     * Never throws: any error means the gate did not pass, and the run continues as it would have.
+     */
+    async evaluateFinishIf(finishIf, state, params, decision, payload, parentStepId) {
+        const settings = this.finishIfSettings();
+        let step;
+        let outcome;
+        try {
+            step = await this.createStepEntity({
+                stepType: 'Decision',
+                stepName: 'Finish check',
+                contextUser: params.contextUser,
+                inputData: { questions: finishIf.questions, state: state.slice(0, FINISH_IF_STATE_EXCERPT) },
+                parentId: parentStepId
+            });
+            outcome = await this.askFinishIf(finishIf, state, settings, params, step);
+            if (outcome.Passed) {
+                const refusal = await this.finishIfValidationRefusal(params, this.finishIfSuccessStep(finishIf, decision, payload), payload, step);
+                if (refusal) {
+                    outcome = { ...outcome, Passed: false, Reason: refusal };
+                }
+            }
+        }
+        catch (error) {
+            outcome = { Passed: false, Probabilities: {}, Reason: error instanceof Error ? error.message : String(error) };
+            LogError(`finishIf gate failed, so the run continues: ${outcome.Reason}`);
+        }
+        await this.finalizeFinishCheckStep(step, outcome, settings);
+        return outcome;
+    }
+    /**
+     * Asks each finishIf question as a Likelihood. Every one must reach the threshold. The call's
+     * prompt run is linked to the `Finish check` step, so the run's cost and tokens count it.
+     */
+    async askFinishIf(finishIf, state, settings, params, step) {
+        const questions = BuildFinishIfQuestions(finishIf);
+        const result = await this._agentDecisionService.Ask({
+            State: state,
+            Questions: questions,
+            ContextUser: params.contextUser,
+            AgentID: params.agent?.ID,
+            PromptName: settings.PromptName,
+            CancellationToken: params.cancellationToken,
+            ExecutionScope: this.runPromptExecutionScope(params)
+        });
+        this.attachDecisionPromptRun(step, result);
+        if (!result.success) {
+            return { Passed: false, Probabilities: {}, Reason: `The decision call failed: ${result.errorMessage ?? 'no error message'}` };
+        }
+        return JudgeFinishIf(result.Answers, questions, settings.Threshold);
+    }
+    /**
+     * Returns why the normal Success validation would refuse to end the run, or `undefined` when it
+     * allows it. The check must not count as a validation retry, so the counters are restored:
+     * otherwise a gate that keeps not passing could exhaust the retries and fail the run.
+     */
+    async finishIfValidationRefusal(params, successStep, payload, step) {
+        if (!this._agentRun) {
+            return 'There is no agent run to validate against';
+        }
+        const generalRetries = this._generalValidationRetryCount;
+        const payloadRetries = this._validationRetryCount;
+        try {
+            const validated = await this.validateSuccessNextStep(params, successStep, payload, this._agentRun, step);
+            if (validated.step === 'Success') {
+                return undefined;
+            }
+            return validated.errorMessage || validated.retryInstructions || `Success validation returned '${validated.step}'`;
+        }
+        finally {
+            this._generalValidationRetryCount = generalRetries;
+            this._validationRetryCount = payloadRetries;
+        }
+    }
+    /** The Success step a passing gate returns after actions, in the shape of the client-tools `terminateAfterExecution` branch. */
+    finishIfSuccessStep(finishIf, decision, payload) {
+        return {
+            step: 'Success',
+            terminate: true,
+            message: finishIf.message,
+            payloadChangeRequest: decision.payloadChangeRequest,
+            previousPayload: decision.previousPayload,
+            newPayload: payload,
+            scratchpad: decision.scratchpad,
+            responseForm: decision.responseForm,
+            actionableCommands: decision.actionableCommands,
+            automaticCommands: decision.automaticCommands,
+            artifactDirective: decision.artifactDirective
+        };
+    }
+    /** Finalizes the `Finish check` step with the outcome. A failure to save it never affects the run. */
+    async finalizeFinishCheckStep(step, outcome, settings) {
+        if (!step) {
+            return;
+        }
+        try {
+            await this.finalizeStepEntity(step, true, undefined, {
+                passed: outcome.Passed,
+                mode: settings.Mode,
+                endedRun: outcome.Passed && settings.Mode === 'on',
+                threshold: settings.Threshold,
+                probabilities: outcome.Probabilities,
+                reason: outcome.Reason
+            });
+        }
+        catch (error) {
+            LogError(`Could not save the finishIf step: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Whether the merged agent-type prompt params turn the payload change check on. It is off unless
+     * the master switch ({@link DecisionsEnabled}) and `payloadFeedbackCheck` are both `true`.
+     */
+    isPayloadFeedbackCheckOn(agentTypePromptParams) {
+        return this.DecisionsEnabled(agentTypePromptParams) && agentTypePromptParams?.payloadFeedbackCheck === true;
+    }
+    /**
+     * Runs the payload change check ({@link checkPayloadChanges}) on a step's applied payload changes
+     * when it applies: the analyzer flagged a change for feedback, the check is on
+     * ({@link isPayloadFeedbackCheckOn}), and a turn will read the result. A step that ends the run
+     * skips it: no call to pay for, and no message left in the conversation. Never throws.
+     */
+    async checkPayloadChangesWhenOn(changeResult, nextStep, promptResult, agentTypePromptParams, params) {
+        if (!changeResult.requiresFeedback || !this.isPayloadFeedbackCheckOn(agentTypePromptParams)) {
+            return;
+        }
+        if (this.stepEndsRun(nextStep)) {
+            this.logStatus(`[Payload check] Skipped: the ${nextStep.step} step ends the run, so no turn would read the result`, true, params);
+            return;
+        }
+        await this.checkPayloadChanges(changeResult.analysis, nextStep, promptResult, agentTypePromptParams, params);
+    }
+    /**
+     * Whether the step ends the run, so no turn would read the payload change check's message: it
+     * terminates, or it is a `Success` or `Chat` step, which hand the run back to the caller.
+     */
+    stepEndsRun(step) {
+        return step.terminate === true || step.step === 'Success' || step.step === 'Chat';
+    }
+    /**
+     * The payload change check. Asks whether each change the analyzer flagged was intended, as one
+     * Likelihood per change in one decision call, and records it as a `Payload change check`
+     * Decision step. The changes judged unintended are listed in a message for the agent's next
+     * turn, which asks it to confirm or restore them.
+     *
+     * It never reverts or blocks a change: the agent decides. When the decision cannot answer,
+     * every change is accepted, as it is with the check off. Never throws.
+     */
+    async checkPayloadChanges(analysis, nextStep, promptResult, agentTypePromptParams, params) {
+        const promptName = agentTypePromptParams?.decisionPromptName;
+        const manager = new PayloadFeedbackManager({ decisionPromptName: typeof promptName === 'string' ? promptName : undefined }, this._agentDecisionService);
+        const questions = manager.GenerateQuestions(analysis?.warnings ?? []);
+        if (questions.length === 0) {
+            return;
+        }
+        let step;
+        try {
+            step = await this.createStepEntity({
+                stepType: 'Decision',
+                stepName: 'Payload change check',
+                contextUser: params.contextUser,
+                inputData: {
+                    questions: questions.map(q => ({ id: q.id, path: q.warning.path, type: q.warning.type, change: manager.DescribeChange(q.warning) }))
+                }
+            });
+            const responses = await manager.QueryAgent(questions, this.payloadFeedbackContext(nextStep, promptResult, params), params.contextUser);
+            // Like every decision call, it counts toward the run's cost and tokens through its step
+            if (manager.LastDecisionResult) {
+                this.attachDecisionPromptRun(step, manager.LastDecisionResult);
+            }
+            await this.finalizePayloadCheckStep(step, questions, responses, manager.IntendedThreshold);
+            const message = manager.BuildUnintendedChangesMessage(questions, responses);
+            if (message) {
+                this.injectPayloadCheckMessage(params, message);
+            }
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            LogError(`The payload change check failed, so every change stands: ${reason}`);
+            if (step) {
+                await this.finalizeStepEntity(step, false, reason);
+            }
+        }
+    }
+    /**
+     * What the payload change check's decision reads: the agent's own reasoning for the step (from its
+     * response, else from the step), its message, and the reasoning it gave with the change. The check
+     * never runs on a `Chat` or `Success` step, so the message comes from the response alone.
+     */
+    payloadFeedbackContext(nextStep, promptResult, params) {
+        const response = responseReasoningAndMessage(promptResult?.result);
+        return {
+            Reasoning: response.Reasoning ?? nextStep.reasoning,
+            ChangeReasoning: nextStep.payloadChangeRequest?.reasoning,
+            Message: response.Message,
+            AgentID: params.agent?.ID ?? this._agentRun?.AgentID,
+            CancellationToken: params.cancellationToken,
+            ExecutionScope: this.runPromptExecutionScope(params)
+        };
+    }
+    /**
+     * Finalizes the `Payload change check` step with each change's probability and outcome. The step
+     * fails when no decision answered, and its error says why. A failure to save it never affects the run.
+     */
+    async finalizePayloadCheckStep(step, questions, responses, threshold) {
+        const answered = responses.filter(r => typeof r.probability === 'number');
+        const unintended = responses.filter(r => !r.intended).map(r => questions.find(q => q.id === r.questionId)?.warning.path);
+        try {
+            await this.finalizeStepEntity(step, answered.length > 0, answered.length > 0 ? undefined : responses[0]?.explanation, {
+                threshold,
+                probabilities: Object.fromEntries(answered.map(r => [r.questionId, r.probability])),
+                responses,
+                unintendedPaths: unintended
+            });
+        }
+        catch (error) {
+            LogError(`Could not save the payload change check step: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /** Adds the payload change check's message to the conversation, for the agent's next turn. */
+    injectPayloadCheckMessage(params, content) {
+        const message = {
+            role: 'user',
+            content,
+            metadata: {
+                turnAdded: this._promptTurnCount,
+                messageType: 'tool-result',
+                expirationTurns: 3,
+                expirationMode: 'Compact',
+                compactMode: 'First N Chars',
+                compactLength: 500,
+                compactPromptId: '',
+            },
+        };
+        params.conversationMessages.push(message);
+    }
+    /**
+     * The {@link AIPromptExecutionScope} of model work this run starts outside the agent's own turn —
+     * summarizing a range, compacting a message or the conversation, decision calls (FinishIf,
+     * discovery, catalog narrowing, decision requests, the payload change check) and self-check
+     * rubrics. Each built its params with only `contextUser`, so it ran on the platform's keys and
+     * default configuration inside a run on a customer's keys, and under a `'RuntimeOnly'` scope
+     * would have bypassed it.
+     */
+    runPromptExecutionScope(params) {
+        return {
+            contextUser: params.contextUser,
+            provider: params.provider || this._activeProvider,
+            configurationId: params.configurationId,
+            apiKeys: params.apiKeys,
+            CredentialScope: params.CredentialScope,
+        };
+    }
     /**
      * Whether THIS action may use the run's runtime API key for THIS driver class. The default is
      * yes: the run was started on those keys, and an action that calls a vendor on the user's behalf
      * (Generate Image) is doing what the prompts do. Override to narrow it — an agent that knows
      * which of its actions talk to which vendor can refuse everything else, and a refusal costs the
      * action nothing but the customer's key: it falls back to the platform key as if the run had none.
+     * Under a `'RuntimeOnly'` credential scope a refusal leaves the action with no key for that class.
      */
     actionMayUseRuntimeAPIKey(action, driverClass, params) {
         return true;
@@ -6829,12 +8448,14 @@ The context is now within limits. Please retry your request with the recovered c
     buildRuntimeAPIKeyResolver(params, actionEntity) {
         const runKeys = params.apiKeys;
         return (driverClass) => {
+            const platformAllowed = CredentialScopeAllows(params.CredentialScope, 'Environment');
             if (!this.actionMayUseRuntimeAPIKey(actionEntity, driverClass, params)) {
-                this.logStatus(`🔑 Runtime API key for '${driverClass}' refused to action '${actionEntity.Name}' by policy — platform key applies`, true, params);
+                this.logStatus(`🔑 Runtime API key for '${driverClass}' refused to action '${actionEntity.Name}' by policy — ${platformAllowed ? 'platform key applies' : `credential scope is ${params.CredentialScope}, so no key applies`}`, true, params);
                 return undefined;
             }
-            const key = GetAIAPIKey(driverClass, runKeys);
-            this.logStatus(`🔑 Action '${actionEntity.Name}' resolved an API key for '${driverClass}' (${runKeys?.some((k) => k.driverClass === driverClass) ? 'run' : 'platform'})`, true, params);
+            const key = GetAIAPIKey(driverClass, runKeys, false, params.CredentialScope);
+            const source = runKeys?.some((k) => k.driverClass === driverClass) ? 'run' : platformAllowed ? 'platform' : `none — credential scope is ${params.CredentialScope}`;
+            this.logStatus(`🔑 Action '${actionEntity.Name}' resolved an API key for '${driverClass}' (${source})`, true, params);
             return key || undefined;
         };
     }
@@ -6901,8 +8522,12 @@ The context is now within limits. Please retry your request with the recovered c
                 // shared by every action in the run (parallel ones included) and copied into sub-agent
                 // runs, so anything stamped there would name the wrong action under parallel dispatch
                 // and travel further than the action it was meant for. Absent when the run has no keys,
-                // so the action uses GetAIAPIKey(driverClass) exactly as before.
+                // so the action uses GetAIAPIKey(driverClass) exactly as before — unless the scope below
+                // is RuntimeOnly, which tells the action the resolver's answer (or its absence) is final.
                 RuntimeAPIKeyResolver: params.apiKeys && params.apiKeys.length > 0 ? this.buildRuntimeAPIKeyResolver(params, actionEntity) : undefined,
+                // AICredentialScope → actions-base's RuntimeCredentialScope mirror: a value added to the
+                // former and not the latter fails to compile here, so the two cannot drift apart.
+                CredentialScope: params.CredentialScope,
             });
             if (result.Success) {
                 this.logStatus(`   ✅ Action '${action.name}' completed successfully`, true, params);
@@ -7153,6 +8778,7 @@ The context is now within limits. Please retry your request with the recovered c
                 configurationId: params.configurationId, // propagate configuration ID to sub-agent
                 effortLevel: params.effortLevel, // propagate effort level to sub-agent
                 apiKeys: params.apiKeys, // propagate API keys to sub-agent
+                CredentialScope: params.CredentialScope, // a sub-agent may not spend keys its parent could not
                 inputArtifacts: params.inputArtifacts, // propagate input artifacts so sub-agents inherit the parent's artifact manifest + tools (e.g. a Codesmith delegate can read a Data Snapshot the parent references)
                 data: {
                     ...params.data,
@@ -7845,6 +9471,7 @@ The context is now within limits. Please retry your request with the recovered c
         }
         // Reset prompt turn counter for this execution
         this._promptTurnCount = 0;
+        this._heldDecisions = undefined;
         // Resolve action-result compression config for this run (default on; opt out via
         // crushActionResults: false in the agent-type prompt params).
         this._actionResultCrush = this.resolveActionResultCrush(params);
@@ -8510,12 +10137,15 @@ The context is now within limits. Please retry your request with the recovered c
                     }
                 }
                 return await this.executePromptStep(params, config, previousDecision, stepCount);
-            case 'Sub-Agent':
+            case 'Sub-Agent': {
                 // A Sub-Agent step carrying a task graph is a FOLDED graph (D9): the agent type
                 // rewrote a one-node graph into an ordinary in-run call. Record it before running,
                 // so the run shows what was emitted even if the sub-agent then fails.
                 await this.recordFoldedTaskGraph(params, previousDecision);
-                return await this.processSubAgentStep(params, previousDecision, undefined, undefined, stepCount);
+                const subAgentResult = await this.processSubAgentStep(params, previousDecision, undefined, undefined, stepCount);
+                const afterSubAgent = (await this.finishAfterSubAgent(params, previousDecision, subAgentResult)) ?? subAgentResult;
+                return this.selfCheckSuccess(params, afterSubAgent, afterSubAgent.newPayload ?? subAgentResult.newPayload);
+            }
             case 'Actions':
                 return await this.executeActionsStep(params, previousDecision, undefined, true, stepCount, this.actionOptionsForAgentType());
             // Type assertion required because 'Skill' is not part of the BaseAgentNextStep step
@@ -8537,6 +10167,11 @@ The context is now within limits. Please retry your request with the recovered c
             // step union — LoopAgentType.DetermineNextStep() emits it when the LLM chooses client tools.
             case 'ClientTools':
                 return await this.executeClientToolsStep(params, config, previousDecision, stepCount);
+            // Type assertion required because 'Decision' is not part of the BaseAgentNextStep step
+            // union — FlowAgentType emits it for a Decision step, which is one decision call and no
+            // LLM turn. executeDecisionStep returns a 'Retry' carrying the answers.
+            case 'Decision':
+                return await this.executeDecisionStep(params, previousDecision);
             case 'Chat':
                 return await this.executeChatStep(params, previousDecision);
             case 'Success':
@@ -8675,6 +10310,9 @@ The context is now within limits. Please retry your request with the recovered c
      * @private
      */
     async executePromptStep(params, config, previousDecision, stepCount = 0) {
+        // Decisions the last prompt held back: the step that carried them did not end the run, so
+        // answer them now, where this prompt will read the answers
+        await this.runHeldDecisions(params);
         // Ask the agent type if it has a custom prompt for this step
         const promptToUse = await this.AgentTypeInstance.GetPromptForStep(params, config, previousDecision?.newPayload || previousDecision?.previousPayload, this.AgentTypeState, previousDecision);
         const promptId = promptToUse?.ID;
@@ -8858,6 +10496,10 @@ The context is now within limits. Please retry your request with the recovered c
                 currentStepPayloadChangeResult = this.buildPayloadChangeResultSummary(changeResult);
                 // Set the final payload - the changeResult already respects the allowed paths
                 finalPayload = changeResult.result;
+                // Opt-in payload change check: asks whether the flagged changes were intended. It never
+                // reverts or blocks a change; the agent reads the result on its next turn.
+                const payloadCheckParams = promptParams.data?.__agentTypePromptParams;
+                await this.checkPayloadChangesWhenOn(changeResult, initialNextStep, promptResult, payloadCheckParams, params);
             }
             // Apply scratchpad changes if provided (zero turn cost — processed inline)
             if (initialNextStep.scratchpad) {
@@ -8916,6 +10558,13 @@ The context is now within limits. Please retry your request with the recovered c
                 const pipelineResult = await this.executePipelineAsStep(initialNextStep.pipeline, params);
                 this.injectPipelineResultMessage(params, pipelineResult);
             }
+            // Execute decision requests if provided (zero turn cost — processed inline), unless the
+            // step that carries them can end the run: then they are held until it has run
+            const decisions = initialNextStep.decisions;
+            if (decisions?.length) {
+                const agentTypePromptParams = promptParams.data?.__agentTypePromptParams;
+                await this.processTurnDecisions(decisions, initialNextStep, finalPayload, agentTypePromptParams, params);
+            }
             // now that we have processed the payload, we can process the next step which does validation and changes the next step if
             // validation fails
             const updatedNextStep = await this.processNextStep(initialNextStep, params, config.agentType, promptResult, finalPayload, stepEntity);
@@ -9567,8 +11216,10 @@ The context is now within limits. Please retry your request with the recovered c
      * by one in-flight sub-agent would race the others' reads.
      *
      * Uses `structuredClone` (Node 17+) where available; falls back to a JSON
-     * round-trip for environments without it. Returns the original value on
-     * non-cloneable inputs.
+     * round-trip (`ToPlainJSON`) for environments without it AND when
+     * `structuredClone` throws (a Proxy such as a live JSONType `<Field>Object`
+     * view, or functions). Returns the original value — with an error logged —
+     * only when even the JSON clone fails.
      *
      * **JSON fallback caveats** — the round-trip is *not* shape-preserving:
      *   - `Date` → ISO string
@@ -9590,13 +11241,22 @@ The context is now within limits. Please retry your request with the recovered c
             return payload;
         if (typeof payload !== 'object')
             return payload;
-        try {
-            if (typeof globalThis.structuredClone === 'function') {
+        if (typeof globalThis.structuredClone === 'function') {
+            try {
                 return globalThis.structuredClone(payload);
             }
-            return JSON.parse(JSON.stringify(payload));
+            catch {
+                // DataCloneError — typically a Proxy (a live JSONType `<Field>Object` view) or an
+                // object holding functions. Fall through to the JSON clone below; returning the
+                // original here would silently give the sub-agent the caller's LIVE object and lose
+                // payload isolation.
+            }
         }
-        catch {
+        try {
+            return ToPlainJSON(payload);
+        }
+        catch (error) {
+            LogError(`BaseAgent.cloneSubAgentPayload: payload could not be cloned (${error instanceof Error ? error.message : String(error)}); sub-agent will share the caller's object`);
             return payload;
         }
     }
@@ -10718,6 +12378,10 @@ The context is now within limits. Please retry your request with the recovered c
             catch (error) {
                 LogError(`Error in PostProcessActionStep: ${error.message}`);
             }
+            const finished = await this.finishAfterActions(params, previousDecision, actionResults, actionSummaries, finalPayload, parentStepId, addConversationMessage);
+            if (finished) {
+                return this.selfCheckSuccess(params, finished, finalPayload);
+            }
             // After actions complete, we need to process the results
             // The retry step is used to re-execute the prompt with the action results
             // This allows the agent to analyze the results and determine what to do next
@@ -10837,7 +12501,7 @@ The context is now within limits. Please retry your request with the recovered c
         // If the LLM already declared taskComplete=true alongside the client tools,
         // honor that intent now that tools have executed — no need for another LLM call.
         if (previousDecision.terminateAfterExecution) {
-            return {
+            return this.selfCheckSuccess(params, {
                 step: 'Success',
                 terminate: true,
                 message: previousDecision.message || 'Client tools executed successfully.',
@@ -10850,7 +12514,7 @@ The context is now within limits. Please retry your request with the recovered c
                 // own artifact directive has to come along. Omitting it silently discarded the
                 // instruction whenever an agent declared client tools and taskComplete together.
                 artifactDirective: previousDecision.artifactDirective
-            };
+            }, previousDecision.newPayload);
         }
         return await this.executePromptStep(params, config, previousDecision, stepCount);
     }
@@ -10939,6 +12603,8 @@ The context is now within limits. Please retry your request with the recovered c
      * them calls this after MJ's gates
      * (AcceptsSkills, Status, agent grant, user Run permission, the ActivationMode double gate) and
      * before anything activates. The default is the identity: MJ's gates are the whole policy.
+     * Catalog narrowing (plan Task 3.7) is not part of this policy: it runs after it, at the catalog
+     * site, and only hides skills from the prompt. An override never needs to call `super` for it.
      *
      * Override it to layer a policy MJ has no table for — a tenant licensing model, a per-organization
      * entitlement, a feature flag — and it applies everywhere at once. Without this seam a subclass
@@ -12794,8 +14460,10 @@ The context is now within limits. Please retry your request with the recovered c
         // Iterate through the agent run's steps to sum up tokens
         if (this._agentRun?.Steps) {
             for (const step of this._agentRun.Steps) {
-                if ((step.StepType === 'Prompt' || step.StepType === 'Compaction') && step.PromptRun) {
-                    // Add tokens from prompt runs (rollup fields include any nested child prompt runs)
+                if ((step.StepType === 'Prompt' || step.StepType === 'Compaction' || step.StepType === 'Decision') && step.PromptRun) {
+                    // Add tokens from prompt runs (rollup fields include any nested child prompt runs).
+                    // A Decision step carries its own decision call's run — the Finish check, a single-state
+                    // request, or one item of a forEachItemIn request — so each call is counted once.
                     totalTokens += step.PromptRun.TokensUsedRollup || 0;
                     promptTokens += step.PromptRun.TokensPromptRollup || 0;
                     completionTokens += step.PromptRun.TokensCompletionRollup || 0;
@@ -13177,6 +14845,7 @@ The context is now within limits. Please retry your request with the recovered c
             Budget: budget,
             ContextUser: params.contextUser,
             Provider: this.ProviderToUse,
+            ExecutionScope: this.runPromptExecutionScope(params),
             EstimateTokens: (messages) => this.estimateConversationTokens(messages),
             Verbose: params.verbose,
             // The in-flight agent-response placeholder row: a post-turn pass runs while
@@ -13401,6 +15070,7 @@ The context is now within limits. Please retry your request with the recovered c
                     const step = await this.createCompactionStep(prompt, message, params);
                     // Execute summarization prompt
                     const promptParams = new AIPromptParams();
+                    Object.assign(promptParams, this.runPromptExecutionScope(params));
                     promptParams.prompt = prompt;
                     promptParams.data = {
                         originalContent,
@@ -13409,7 +15079,6 @@ The context is now within limits. Please retry your request with the recovered c
                         messageType: message.metadata?.messageType || 'unknown',
                         turnAdded: message.metadata?.turnAdded || 0
                     };
-                    promptParams.contextUser = params.contextUser;
                     promptParams.agentId = params.agent.ID;
                     promptParams.UserID = ResolvePromptRunUserID({
                         UserID: params.userId,