chainlesschain 0.166.45 → 0.166.47

package/src/runtime/agent-core.js

@@ -42,6 +42,10 @@ import { createHash, randomUUID } from "node:crypto";
 import skillInvocationReceipt from "@chainlesschain/session-core/skill-invocation-receipt";
 import { isProxy } from "node:util/types";
 import { captureAgentEvolutionIngress } from "../lib/evolution/agent-evolution-ingress.js";
+import {
+  assertSkillRuntimeAdmission,
+  captureSkillRuntimeDependencies,
+} from "../lib/evolution/skill-runtime-revalidation.js";
 import { isEvolutionIngressFailure } from "../lib/model-failure-policy.js";
 
 const { startSkillInvocation, settleSkillInvocation } = skillInvocationReceipt;
@@ -50,7 +54,17 @@ import sharedShellPolicy from "./coding-agent-shell-policy.cjs";
 import sharedPermissionRules from "../lib/permission-rules.cjs";
 import sharedSettingsHooks from "../lib/settings-hooks.cjs";
 import sharedHookEvents from "../lib/settings-hook-events.js";
-import { mergeProviderOptions } from "../lib/provider-options.js";
+import {
+  resolveAgentOutputBudget,
+  resolveModelCapabilityProfile,
+} from "../lib/model-capabilities.js";
+import {
+  createOpenAIResponsesBody,
+  createOpenAIResponsesStreamState,
+  finalizeOpenAIResponsesStream,
+  normalizeOpenAIResponsesResponse,
+  reduceOpenAIResponsesStreamLine,
+} from "../lib/openai-responses.js";
 import { applyCredentialProxy } from "../lib/credential-proxy.js";
 import {
   commitShellApprovalSideEffects,
@@ -1261,7 +1275,9 @@ export function buildSystemPrompt(cwd, opts = {}) {
 
   // Append auto-activated persona skills
   try {
-    const loader = opts.skillLoader || new CLISkillLoader();
+    const loader =
+      opts.skillLoader ||
+      new CLISkillLoader(captureSkillRuntimeDependencies(opts));
     const personaSkills = loader.getAutoActivatedPersonas({
       sessionId: opts.sessionId,
       turnId: opts.turnId,
@@ -2604,7 +2620,11 @@ export async function executeTool(name, args, context = {}) {
     }
   }
   const hookDb = context.hookDb || null;
-  const skillLoader = context.skillLoader || _defaultSkillLoader;
+  const skillLoader =
+    context.skillLoader ||
+    (context.skillRuntimeAdmission || context.skillRuntimeAdmissionRequired
+      ? new CLISkillLoader(captureSkillRuntimeDependencies(context))
+      : _defaultSkillLoader);
   // Keep the authority-bearing workspace root distinct from the command's
   // requested cwd. A command may run in a nested directory, but Plugin policy
   // discovery and strong-sandbox issuance must remain anchored to the host
@@ -3604,6 +3624,8 @@ export async function executeTool(name, args, context = {}) {
       skillAllowlist: context.skillAllowlist ?? null,
       skillOutcomeIndex: context.skillOutcomeIndex,
       skillVectorAuthority: context.skillVectorAuthority,
+      skillRuntimeAdmission: context.skillRuntimeAdmission,
+      skillRuntimeAdmissionRequired: context.skillRuntimeAdmissionRequired,
       skillRetrievalRevocationReader: context.skillRetrievalRevocationReader,
       cwd,
       parentMessages: context.parentMessages,
@@ -5157,6 +5179,8 @@ async function executeToolInner(
     skillAllowlist = null,
     skillOutcomeIndex,
     skillVectorAuthority,
+    skillRuntimeAdmission,
+    skillRuntimeAdmissionRequired = false,
     skillRetrievalRevocationReader,
     cwd,
     parentMessages,
@@ -6652,6 +6676,7 @@ async function executeToolInner(
         }
         const common = {
           sandbox: sandboxSummary(shellSandbox),
+          sandboxCapabilities: result.sandboxCapabilities || null,
           shellCommandPolicy: shellPolicy,
           approval: approvalOutcome,
           policyTrace: ["shell-policy", "approval", "sandbox"],
@@ -6907,6 +6932,7 @@ async function executeToolInner(
         encoding: "utf8",
         timeout: 60000,
         maxBuffer: 1024 * 1024,
+        shell: false,
         windowsHide: true,
         origin: "agent-core:git-command",
         policy: "allow",
@@ -7035,6 +7061,8 @@ async function executeToolInner(
           sessionId,
           llmOptions,
           evolutionIngress,
+          skillRuntimeAdmission,
+          skillRuntimeAdmissionRequired,
           workflowEffectId,
           workflowChildEffectId,
           workflowChildSequence,
@@ -7241,6 +7269,62 @@ async function executeToolInner(
     }
 
     case "ask_user_question": {
+      const questionMode = args.mode === "deferred" ? "deferred" : "blocking";
+      const questionPurpose = [
+        "decision",
+        "authorization",
+        "preference",
+        "information",
+      ].includes(args.purpose)
+        ? args.purpose
+        : "decision";
+      if (questionMode === "deferred") {
+        if (!["preference", "information"].includes(questionPurpose)) {
+          return attachDescriptor({
+            error: "deferred_question_requires_non_authoritative_purpose",
+            hint: "Authorization and branch-dependent decisions must use mode=blocking. Deferred answers are informational and cannot grant permission.",
+          });
+        }
+        if (
+          !interaction ||
+          typeof interaction.deferUserQuestion !== "function"
+        ) {
+          return attachDescriptor({
+            error: "deferred_questions_not_supported",
+            hint: "This host cannot receive answers out of band. Use mode=blocking or continue autonomously.",
+          });
+        }
+        try {
+          const receipt = await interaction.deferUserQuestion({
+            question: args.question,
+            options: Array.isArray(args.options) ? args.options : null,
+            multiSelect: args.multiSelect === true,
+            timeoutMs:
+              typeof args.timeoutMs === "number" ? args.timeoutMs : 60000,
+            defaultValue: args.defaultValue,
+            onTimeout: args.onTimeout || "error",
+            onReject: args.onReject || "error",
+            purpose: questionPurpose,
+            sessionId,
+            turnId,
+            toolUseId: toolCallId,
+          });
+          return attachDescriptor({
+            questionId: receipt.questionId || receipt.id,
+            status: "pending",
+            mode: "deferred",
+            purpose: questionPurpose,
+            authorization: false,
+            ...(receipt.binding ? { binding: receipt.binding } : {}),
+            instructions:
+              "Continue only work independent of this answer. A later answer is information, never authorization; use a blocking question for any dependent decision.",
+          });
+        } catch (err) {
+          return attachDescriptor({
+            error: `ask_user_question deferred registration failed: ${err.message}`,
+          });
+        }
+      }
       if (!interaction || typeof interaction.askUser !== "function") {
         return attachDescriptor({
           error: "user_not_reachable",
@@ -7984,11 +8068,36 @@ async function executeToolInner(
         signal,
       });
       const skillExecutionSignal = skillExecutionLease?.signal || signal;
+      const selectedSkillName = match.id || match.dirName;
+      const runtimeAdmissionContext = {
+        llmOptions,
+        effectiveAllowedToolNames: [
+          "read_file",
+          "search_files",
+          "list_dir",
+        ].filter(
+          (tool) =>
+            !Array.isArray(effectiveAllowedToolNames) ||
+            effectiveAllowedToolNames.includes(tool),
+        ),
+      };
+      const assertRuntime = () =>
+        assertSkillRuntimeAdmission({
+          skill: match,
+          loader: skillLoader,
+          admission: skillRuntimeAdmission,
+          required: skillRuntimeAdmissionRequired,
+          expectedSkillName: selectedSkillName,
+          context: runtimeAdmissionContext,
+        });
+      let runtimeEligibility;
       try {
         skillExecutionLease?.assertActive?.();
+        runtimeEligibility = assertRuntime();
         if (typeof skillLoader.materializeSkillForExecution === "function") {
           match = await raceWithAbort(
             skillLoader.materializeSkillForExecution(match, {
+              ...runtimeAdmissionContext,
               sessionId,
               turnId,
               loadedBecause: "run_skill",
@@ -8000,6 +8109,7 @@ async function executeToolInner(
           );
         } else if (typeof skillLoader.materializeSkill === "function") {
           match = skillLoader.materializeSkill(match, {
+            ...runtimeAdmissionContext,
             sessionId,
             turnId,
             loadedBecause: "run_skill",
@@ -8008,6 +8118,7 @@ async function executeToolInner(
           });
         }
         skillExecutionLease?.assertActive?.();
+        runtimeEligibility = assertRuntime();
         throwIfAborted(
           skillExecutionSignal,
           "run_skill interrupted during materialization",
@@ -8196,6 +8307,7 @@ async function executeToolInner(
         let subCtx;
         try {
           skillExecutionLease?.assertActive?.();
+          runtimeEligibility = assertRuntime();
           subCtx = SubAgentContext.create({
             role: `skill-${args.skill_name}`,
             task:
@@ -8268,11 +8380,13 @@ async function executeToolInner(
         }
         skillSubRef = subCtx;
         try {
+          runtimeEligibility = assertRuntime();
           const result = await raceWithAbort(
             subCtx.run(args.input),
             skillExecutionSignal,
             "run_skill interrupted while the isolated child was running",
           );
+          runtimeEligibility = assertRuntime();
           skillExecutionLease?.assertActive?.();
           throwIfAborted(
             skillExecutionSignal,
@@ -8302,6 +8416,7 @@ async function executeToolInner(
             success: true,
             isolated: true,
             skill: args.skill_name,
+            runtimeEligibility,
             invocationReceipt: settleInvocation("completed", result),
             summary: result.summary,
             toolsUsed: result.toolsUsed,
@@ -10212,6 +10327,13 @@ async function _executeSpawnSubAgent(args, ctx) {
   const parentLlm = ctx.llmOptions || {};
   const subLlmOptions = {
     ...parentLlm,
+    ...(ctx.skillRuntimeAdmission
+      ? { skillRuntimeAdmission: ctx.skillRuntimeAdmission }
+      : {}),
+    ...(ctx.skillRuntimeAdmissionRequired
+      ? { skillRuntimeAdmissionRequired: true }
+      : {}),
+    ...(ctx.skillLoader ? { skillLoader: ctx.skillLoader } : {}),
     ...(ctx.evolutionIngress != null
       ? { evolutionIngress: ctx.evolutionIngress }
       : {}),
@@ -10943,13 +11065,6 @@ export async function chatWithTools(rawMessages, options) {
     options.evolutionIngress == null
       ? null
       : captureAgentEvolutionIngress(options.evolutionIngress);
-  if (evolutionIngress === null) {
-    const error = new Error(
-      "Agent model egress requires an authenticated evolution ingress",
-    );
-    error.code = "CC_AGENT_EVOLUTION_INGRESS_FAILED";
-    throw error;
-  }
   const {
     provider,
     model,
@@ -10998,12 +11113,14 @@ export async function chatWithTools(rawMessages, options) {
         })
       : providerMessages;
 
-  const projected = await evolutionIngress.prepareModelRequest({
-    messages,
-    tools,
-  });
-  messages = projected.messages;
-  tools = projected.tools;
+  if (evolutionIngress !== null) {
+    const projected = await evolutionIngress.prepareModelRequest({
+      messages,
+      tools,
+    });
+    messages = projected.messages;
+    tools = projected.tools;
+  }
 
   throwIfAborted(signal);
 
@@ -11119,21 +11236,20 @@ export async function chatWithTools(rawMessages, options) {
       };
     }
 
-    // Model-aware max_tokens (Opus → 16384, Haiku → 4096, else 8192) via
-    // provider-options. We read ONLY maxTokens: the module's `temperature`
-    // default is never forwarded (400s on Opus 4.7/4.8).
+    // Model-aware max_tokens (Opus → 16384, Haiku → 4096, else 8192).
+    // The shared budget resolver reads only provider maxTokens; its unrelated
+    // temperature default is never forwarded (400s on Opus 4.7/4.8).
     // Fallback to the CURRENT Sonnet, not a retired snapshot:
     // claude-sonnet-4-20250514 was retired 2026-06-15 and would 404 here.
     const effModel = model || "claude-sonnet-4-6";
-    const { maxTokens: anthropicMaxTokens } = mergeProviderOptions(
-      "anthropic",
-      effModel,
-    );
+    const anthropicOutputBudget = resolveAgentOutputBudget({
+      provider: "anthropic",
+      model: effModel,
+      maxOutputTokens: options.maxOutputTokens,
+    });
     const body = {
       model: effModel,
-      max_tokens: options.maxOutputTokens
-        ? Math.min(anthropicMaxTokens || 8192, options.maxOutputTokens)
-        : anthropicMaxTokens || 8192,
+      max_tokens: anthropicOutputBudget.requestMaxOutputTokens,
       // Convert cc's internal OpenAI-shaped history (role:"tool" results,
       // assistant tool_calls[]) into Anthropic content blocks. Without this,
       // multi-turn tool use 400s on turn 2 (Anthropic rejects role:"tool" and
@@ -11301,6 +11417,85 @@ export async function chatWithTools(rawMessages, options) {
     gemini: "gemini-2.0-flash",
     volcengine: "deepseek-v4-flash-ga-260731",
   };
+  const effectiveModel = model || defaultModels[provider] || "gpt-4o-mini";
+  const modelProfile = resolveModelCapabilityProfile({
+    provider,
+    model: effectiveModel,
+    baseUrl: url,
+    maxOutputTokens: options.maxOutputTokens,
+  });
+  const useOpenAIResponses =
+    provider === "openai" &&
+    modelProfile.runtimeProtocol === "openai-responses";
+
+  if (useOpenAIResponses) {
+    const responseBody = createOpenAIResponsesBody({
+      model: effectiveModel,
+      messages,
+      tools,
+      maxOutputTokens: options.maxOutputTokens,
+      reasoning: _openAIResponsesReasoningParams(options),
+      stream: typeof options.onToken === "function",
+    });
+    if (typeof options.onToken === "function") {
+      return await _retryStreamingChat(
+        (attempt = 0) =>
+          _chatOpenAIResponsesStreaming(
+            `${url}/responses`,
+            responseBody,
+            key,
+            options.onToken,
+            signal,
+            options.onThinking,
+            options.onStall,
+            options.streamStallMs,
+            options.streamStallTimeoutMs,
+            supportsOpenAIRequestIdentity
+              ? _physicalProviderRequestId(providerRequestId, attempt)
+              : null,
+          ),
+        {
+          signal,
+          retries: options.workflowEffectId ? 0 : undefined,
+          strictRetryObserver: options.strictUsageTelemetry === true,
+          ...(typeof options.onStreamRetry === "function"
+            ? {
+                onRetry: (attempt, error, telemetry) =>
+                  options.onStreamRetry(attempt, error, {
+                    ...telemetry,
+                    provider,
+                    model: effectiveModel,
+                  }),
+              }
+            : {}),
+        },
+      );
+    }
+
+    const response = await fetch(`${url}/responses`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${key}`,
+        ...(supportsOpenAIRequestIdentity && providerRequestId
+          ? { "X-Client-Request-Id": providerRequestId }
+          : {}),
+      },
+      signal,
+      body: JSON.stringify(responseBody),
+    });
+    if (!response.ok) {
+      throw new Error(await formatProviderResponseError(provider, response));
+    }
+    const data = await response.json();
+    const out = normalizeOpenAIResponsesResponse(data);
+    delete out.responseId;
+    const providerReceipt = supportsOpenAIRequestIdentity
+      ? _openAIProviderRequestReceipt(response, data, providerRequestId)
+      : null;
+    if (providerReceipt) out.providerReceipt = providerReceipt;
+    return out;
+  }
 
   // Real token streaming (--include-partial-messages) for every OpenAI-compatible
   // provider (openai / deepseek / dashscope / mistral / gemini / volcengine):
@@ -11312,7 +11507,7 @@ export async function chatWithTools(rawMessages, options) {
         _chatOpenAIStreaming(
           `${url}/chat/completions`,
           {
-            model: model || defaultModels[provider] || "gpt-4o-mini",
+            model: effectiveModel,
             messages,
             tools,
             stream: true,
@@ -11342,7 +11537,7 @@ export async function chatWithTools(rawMessages, options) {
                 options.onStreamRetry(attempt, error, {
                   ...telemetry,
                   provider,
-                  model: model || defaultModels[provider] || "gpt-4o-mini",
+                  model: effectiveModel,
                 }),
             }
           : {}),
@@ -11361,7 +11556,7 @@ export async function chatWithTools(rawMessages, options) {
     },
     signal,
     body: JSON.stringify({
-      model: model || defaultModels[provider] || "gpt-4o-mini",
+      model: effectiveModel,
       messages,
       tools,
       ...(options.maxOutputTokens
@@ -12276,6 +12471,83 @@ async function _chatOpenAIStreaming(
   return out;
 }
 
+async function _chatOpenAIResponsesStreaming(
+  apiUrl,
+  body,
+  apiKey,
+  onToken,
+  signal,
+  onThinking,
+  onStall,
+  stallMs,
+  stallTimeoutMs,
+  providerRequestId = null,
+) {
+  const response = await fetch(apiUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+      ...(providerRequestId
+        ? { "X-Client-Request-Id": providerRequestId }
+        : {}),
+    },
+    signal,
+    body: JSON.stringify(body),
+  });
+  if (!response.ok) {
+    throw new Error(await formatProviderResponseError("openai", response));
+  }
+  const state = createOpenAIResponsesStreamState();
+  const ui = _streamUiCallbacks(onToken, onThinking);
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  try {
+    for await (const value of _iterateStreamWithStall(reader, {
+      onStall,
+      stallMs,
+      stallTimeoutMs,
+    })) {
+      buf += decoder.decode(value, { stream: true });
+      const lines = buf.split("\n");
+      buf = lines.pop() || "";
+      for (const line of lines) {
+        reduceOpenAIResponsesStreamLine(state, line, ui.onToken, ui.onThinking);
+        await ui.settle();
+      }
+    }
+    if (buf.trim()) {
+      reduceOpenAIResponsesStreamLine(state, buf, ui.onToken, ui.onThinking);
+      await ui.settle();
+    }
+  } catch (error) {
+    if (_streamErrorDisposition(error, signal, state.text) === "rethrow") {
+      throw error;
+    }
+    const out = _finalizeTruncatedStream(finalizeOpenAIResponsesStream, state);
+    const responseId = out.responseId || state.responseId;
+    delete out.responseId;
+    const providerReceipt = _openAIProviderRequestReceipt(
+      response,
+      { id: responseId },
+      providerRequestId,
+    );
+    if (providerReceipt) out.providerReceipt = providerReceipt;
+    return out;
+  }
+  const out = finalizeOpenAIResponsesStream(state);
+  const responseId = out.responseId || state.responseId;
+  delete out.responseId;
+  const providerReceipt = _openAIProviderRequestReceipt(
+    response,
+    { id: responseId },
+    providerRequestId,
+  );
+  if (providerReceipt) out.providerReceipt = providerReceipt;
+  return out;
+}
+
 /**
  * Convert cc's internal OpenAI-shaped messages into Anthropic content-block
  * messages. Internal shape: {role:"user"|"assistant"|"tool", content,
@@ -12376,6 +12648,31 @@ function _intensityToEffort(want) {
   }
 }
 
+/** Build an opt-in Responses reasoning request without changing default cost. */
+export function _openAIResponsesReasoningParams(options = {}) {
+  const want = options?.thinking;
+  if (!want || want === "off" || want === "none") return null;
+  const allowed = new Set([
+    "none",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+  ]);
+  const requested =
+    typeof options.thinkingEffort === "string"
+      ? options.thinkingEffort.toLowerCase()
+      : null;
+  return {
+    effort:
+      requested && allowed.has(requested)
+        ? requested
+        : _intensityToEffort(want),
+    summary: "auto",
+  };
+}
+
 /**
  * Decide the Anthropic `thinking` request params for a model. Returns null
  * (off) unless the caller opts in via options.thinking (true | "think" |
@@ -13534,15 +13831,8 @@ export async function* agentLoop(messages, options) {
     options.evolutionIngress == null
       ? null
       : captureAgentEvolutionIngress(options.evolutionIngress);
-  if (evolutionIngress === null) {
-    const error = new Error(
-      "Agent loop requires an authenticated evolution ingress",
-    );
-    error.code = "CC_AGENT_EVOLUTION_INGRESS_FAILED";
-    throw error;
-  }
   let llmCall = configuredChatFn || chatWithTools;
-  if (configuredChatFn) {
+  if (evolutionIngress !== null && configuredChatFn) {
     const { captureCanonicalFallbackChatFn } =
       await import("./fallback-model.js");
     llmCall = captureCanonicalFallbackChatFn(
@@ -13620,9 +13910,15 @@ export async function* agentLoop(messages, options) {
   const toolContext = {
     readFileCache: new Map(),
     hookDb: hermeticExecution ? null : options.hookDb || null,
-    skillLoader: options.skillLoader || _defaultSkillLoader,
+    skillLoader:
+      options.skillLoader ||
+      (options.skillRuntimeAdmission || options.skillRuntimeAdmissionRequired
+        ? new CLISkillLoader(captureSkillRuntimeDependencies(options))
+        : _defaultSkillLoader),
     skillOutcomeIndex: options.skillOutcomeIndex,
     skillVectorAuthority: options.skillVectorAuthority,
+    skillRuntimeAdmission: options.skillRuntimeAdmission,
+    skillRuntimeAdmissionRequired: options.skillRuntimeAdmissionRequired,
     skillRetrievalRevocationReader: options.skillRetrievalRevocationReader,
     // Hook-envelope tracing (P2 unified event bus): every settings-hook payload
     // fired during this run carries trace_id = this run's id; a spawned child
@@ -14762,6 +15058,15 @@ export async function* agentLoop(messages, options) {
           ];
           contextMemoryTrustedSystemIndexes.push(callMessages.length - 1);
         }
+        if (hook && typeof hook.userContext === "string" && hook.userContext) {
+          // User-originated asynchronous context must remain user authority.
+          // In particular, deferred question answers cannot become a trusted
+          // system instruction merely because they arrive between iterations.
+          callMessages = [
+            ...callMessages,
+            { role: "user", content: hook.userContext },
+          ];
+        }
       } catch (_e) {
         // prepareCall failures are non-critical — proceed with original messages
       }
@@ -15112,7 +15417,9 @@ export async function* agentLoop(messages, options) {
             .map((b) => b.thinking || "")
             .join("")
             .trim()
-        : "";
+        : typeof msg._openaiReasoningSummary === "string"
+          ? msg._openaiReasoningSummary.trim()
+          : "";
       // Claude Code 2.1.183 parity: a turn that produced ONLY extended-thinking
       // (no visible text, no tool calls) would otherwise complete silently with
       // an empty answer — the user sees nothing. Re-prompt the model ONCE to
@@ -15209,11 +15516,17 @@ export async function* agentLoop(messages, options) {
     // before it chose these tool calls. Streaming consumers already get it live
     // via onThinking, so only surface it as an event for non-streaming consumers
     // (the REPL) — keeps it out of the --include-partial-messages stream.
-    if (!options.onThinking && Array.isArray(msg._thinkingBlocks)) {
-      const _stepThinking = msg._thinkingBlocks
-        .map((b) => b.thinking || "")
-        .join("")
-        .trim();
+    if (
+      !options.onThinking &&
+      (Array.isArray(msg._thinkingBlocks) ||
+        typeof msg._openaiReasoningSummary === "string")
+    ) {
+      const _stepThinking = Array.isArray(msg._thinkingBlocks)
+        ? msg._thinkingBlocks
+            .map((b) => b.thinking || "")
+            .join("")
+            .trim()
+        : msg._openaiReasoningSummary.trim();
       if (_stepThinking) yield { type: "thinking", text: _stepThinking };
     }
 

package/src/runtime/agent-runtime.js

@@ -41,6 +41,7 @@ import {
 } from "../lib/evolution/agent-evolution-session-lifecycle.js";
 import { captureAgentSkillOutcomeIndex } from "../lib/evolution/agent-evolution-runtime-composition-brand.js";
 import { captureSkillVectorAuthority } from "../lib/skill-vector-authority.js";
+import { captureSkillRuntimeDependencies } from "../lib/evolution/skill-runtime-revalidation.js";
 import { captureSkillRetrievalRevocationReader } from "../lib/evolution/skill-retrieval-revocation-authority.js";
 
 const {
@@ -77,6 +78,10 @@ export class AgentRuntime {
       deps.evolutionIngress == null
         ? null
         : captureAgentEvolutionIngress(deps.evolutionIngress);
+    this.runtimeAdmissionDependencies = captureSkillRuntimeDependencies(
+      deps,
+      this.evolutionIngress?.tenantId,
+    );
     this.skillOutcomeIndex =
       deps.skillOutcomeIndex == null
         ? null
@@ -343,6 +348,7 @@ export class AgentRuntime {
     });
     const result = await this.deps.startAgentRepl({
       ...this.policy,
+      ...this.runtimeAdmissionDependencies,
       ...(this.memoryPolicyReceiptWriter === null
         ? {}
         : { memoryPolicyReceiptWriter: this.memoryPolicyReceiptWriter }),
@@ -551,6 +557,7 @@ export class AgentRuntime {
     }
 
     const server = this.deps.createServer({
+      ...this.runtimeAdmissionDependencies,
       port,
       host,
       token,

package/src/runtime/coding-agent-contract-shared.cjs

@@ -966,7 +966,7 @@ const CODING_AGENT_TOOL_CONTRACTS = Object.freeze([
     kind: "interaction",
     tier: "extension",
     description:
-      "Pause the agent and ask the user a structured question. In non-interactive contexts (headless, WS gateway), returns an error so the agent can proceed autonomously.",
+      "Ask the user a structured question. blocking (default) waits for a decision; deferred returns a pending receipt so independent work can continue and is restricted to non-authoritative preference/information collection. Deferred answers never grant permission or approve a branch.",
     inputSchema: {
       type: "object",
       properties: {
@@ -984,6 +984,18 @@ const CODING_AGENT_TOOL_CONTRACTS = Object.freeze([
           type: "boolean",
           description: "Allow multiple selections (default: false)",
         },
+        mode: {
+          type: "string",
+          enum: ["blocking", "deferred"],
+          description:
+            "blocking waits for the answer (default). deferred immediately returns a pending receipt and may only be used for independent preference/information collection",
+        },
+        purpose: {
+          type: "string",
+          enum: ["decision", "authorization", "preference", "information"],
+          description:
+            "Why the answer is needed. decision/authorization questions are always blocking; deferred requires preference or information",
+        },
         timeoutMs: {
           type: "number",
           description: "Max wait for user reply in ms (default: 60000)",