@librechat/agents 4.0.2 → 4.0.4

package/src/tools/subagent/SubagentExecutor.ts

@@ -60,6 +60,7 @@ import type {
   SubagentTaskConfig,
   SubagentTaskRuntime,
   SubagentResolveConfigurable,
+  SubagentHostArgs,
   SubagentResolveRequestContext,
   SubagentResolveUserContext,
   StepCompleted,
@@ -80,6 +81,12 @@ import type {
   SubagentExecutionPreparationLease,
   SubagentExecutionRecord,
 } from './SubagentExecutionRegistry';
+import type {
+  SubagentResolutionPhase,
+  SubagentResolutionCause,
+  SubagentHostArgumentFailure,
+  SubagentResolutionFailureHandler,
+} from './diagnostics';
 import type {
   SubagentResumeExecution,
   SubagentResumeManifest,
@@ -92,11 +99,6 @@ import type {
   PreemptBoundaryHookOutput,
   ToolApprovalReplaySnapshot,
 } from '@/hooks';
-import type {
-  SubagentResolutionPhase,
-  SubagentResolutionCause,
-  SubagentResolutionFailureHandler,
-} from './diagnostics';
 import type { RunBreakerScope } from '@/llm/streamLimits';
 import type { GraphFactory } from '@/graphs/graphFactory';
 import type { StandardGraph } from '@/graphs/Graph';
@@ -114,6 +116,18 @@ import {
   SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY,
   SUBAGENT_RESUME_MANIFEST_CONFIG_KEY,
 } from './SubagentReplay';
+import {
+  logSubagentResolutionFailure,
+  SubagentResolutionError,
+  getSubagentHostArgumentFailure,
+  getSubagentHostArgumentFailureMessage,
+} from './diagnostics';
+import {
+  getSubagentHostArgSpecs,
+  resolveSubagentHostArgs,
+  pickSubagentHostArgInput,
+  getSubagentHostArgsDigest,
+} from './hostArgs';
 import {
   rebindToolBatchReplayScope,
   rebindToolBatchReplayPayload,
@@ -132,10 +146,6 @@ import {
   DEFAULT_SUBAGENT_MAX_TURNS,
   SUBAGENT_RECURSION_MULTIPLIER,
 } from './runtimeLimits';
-import {
-  logSubagentResolutionFailure,
-  SubagentResolutionError,
-} from './diagnostics';
 import {
   ContentTypes,
   Constants,
@@ -147,6 +157,7 @@ import {
   createChildGraphPlan,
   isGraphSubagentConfig,
 } from './childGraphConfig';
+import { ProviderTextProtectionError } from '@/protection/providerText';
 import { stripRunStepResumeState } from '@/tools/runStepResume';
 import { seedAgentInitialSessions } from '@/utils/toolSessions';
 import { stableStringify } from '@/tools/eagerEventExecution';
@@ -178,7 +189,11 @@ const SUBAGENT_INVOCATION_CHANGED_MESSAGE =
 
 function isSubagentResolutionControlFlow(error: unknown): boolean {
   try {
-    return error instanceof StreamLimitExceededError || isGraphInterrupt(error);
+    return (
+      error instanceof StreamLimitExceededError ||
+      error instanceof ProviderTextProtectionError ||
+      isGraphInterrupt(error)
+    );
   } catch {
     return false;
   }
@@ -678,7 +693,8 @@ function getSettlementFingerprint(output: PersistedToolOutput): string {
 function getBackgroundTaskFingerprint(
   description: string,
   subagentType: string,
-  threadId?: string
+  threadId?: string,
+  hostArgsDigest?: string
 ): string {
   return createHash('sha256')
     .update(
@@ -686,11 +702,29 @@ function getBackgroundTaskFingerprint(
         description,
         subagentType,
         ...(threadId == null || threadId === '' ? {} : { threadId }),
+        ...(hostArgsDigest == null ? {} : { hostArgsDigest }),
       })
     )
     .digest('hex');
 }
 
+/** Host-argument digest of persisted lifecycle args, when they are well formed. */
+function getHostArgsDigestFromArgs(
+  config: ExecutableSubagentConfigEntry | undefined,
+  args: unknown
+): string | undefined {
+  if (config == null || !isObjectLike(args)) {
+    return undefined;
+  }
+  const names = new Set(getSubagentHostArgSpecs(config).map(([name]) => name));
+  const picked = pickSubagentHostArgInput(args, names);
+  if (!picked.ok) {
+    return undefined;
+  }
+  const resolved = resolveSubagentHostArgs(config, picked.hostArgs);
+  return resolved.ok ? getSubagentHostArgsDigest(resolved.hostArgs) : undefined;
+}
+
 function getBackgroundTaskHookSessionId(
   sourceHookSessionId: string,
   taskId: string
@@ -877,6 +911,11 @@ export type SubagentExecuteParams = {
   taskRuntime?: SubagentTaskRuntime;
   /** Host-restored child transcript for a fresh continuation run. @internal */
   initialMessages?: BaseMessage[];
+  /**
+   * Values for the selected subagent's declared `hostArgs`. Checked against
+   * the declaration before an execution opens, then bound to it.
+   */
+  hostArgs?: SubagentHostArgs;
 };
 
 export type SubagentExecuteResult = SubagentContextResult & {
@@ -886,6 +925,7 @@ export type SubagentExecuteResult = SubagentContextResult & {
   resolutionFailure?: {
     phase: SubagentResolutionPhase;
     cause: SubagentResolutionCause;
+    hostArgument?: SubagentHostArgumentFailure;
   };
   /** Completed child work whose host projection must be retried without re-execution. */
   retryableDelivery?: true;
@@ -957,6 +997,7 @@ export type SubagentExecutorOptions = {
    * graph's own resolved limits; without this the child would silently
    * revert to the defaults.
    */
+  providerTextProtection?: StandardGraphInput['providerTextProtection'];
   streamLimits?: StandardGraphInput['streamLimits'];
   humanInTheLoop?: HumanInTheLoopConfig;
   /** Shared durable saver used to recover outer tool lifecycle results before
@@ -1034,6 +1075,7 @@ export class SubagentExecutor {
   private readonly executionContext: SubagentExecutionContext;
   private readonly langfuse?: StandardGraphInput['langfuse'];
   private readonly tokenCounter?: TokenCounter;
+  private readonly providerTextProtection?: StandardGraphInput['providerTextProtection'];
   private readonly streamLimits?: StandardGraphInput['streamLimits'];
   private readonly humanInTheLoop?: HumanInTheLoopConfig;
   private readonly checkpointer?: BaseCheckpointSaver;
@@ -1074,6 +1116,7 @@ export class SubagentExecutor {
     this.langfuse = options.langfuse;
     this.tokenCounter = options.tokenCounter;
     this.streamLimits = options.streamLimits;
+    this.providerTextProtection = options.providerTextProtection;
     this.humanInTheLoop = options.humanInTheLoop;
     this.checkpointer = isCheckpointSaver(options.checkpointer)
       ? options.checkpointer
@@ -1148,6 +1191,18 @@ export class SubagentExecutor {
         message: `Unknown subagent type "${params.subagentType}".`,
       });
     }
+    const hostArgResult = resolveSubagentHostArgs(
+      executableConfig,
+      params.hostArgs
+    );
+    if (!hostArgResult.ok) {
+      return JSON.stringify({
+        status: 'rejected',
+        tool: Constants.SUBAGENT,
+        message: hostArgResult.message,
+      });
+    }
+    const { hostArgs } = hostArgResult;
     if (this.maxDepth <= 0) {
       return JSON.stringify({
         status: 'rejected',
@@ -1213,7 +1268,8 @@ export class SubagentExecutor {
       requestFingerprint: getBackgroundTaskFingerprint(
         params.description,
         params.subagentType,
-        subagentThreadId
+        subagentThreadId,
+        getSubagentHostArgsDigest(hostArgs)
       ),
       ...(subagentThreadId == null || subagentThreadId === ''
         ? {}
@@ -1228,6 +1284,7 @@ export class SubagentExecutor {
         this.executeDetached(
           {
             ...params,
+            hostArgs,
             ...(initialMessages == null ? {} : { initialMessages }),
           },
           runtime,
@@ -1344,6 +1401,7 @@ export class SubagentExecutor {
       subagentContext: this.subagentContext,
       onResolutionFailure: this.onResolutionFailure,
       streamLimits: this.streamLimits,
+      providerTextProtection: this.providerTextProtection,
       humanInTheLoop:
         this.humanInTheLoop?.enabled === true ||
         this.humanInTheLoop?.backgroundPausePolicy === 'deny'
@@ -1397,7 +1455,8 @@ export class SubagentExecutor {
         if (result.resolutionFailure != null) {
           throw new SubagentResolutionError(
             result.resolutionFailure.phase,
-            result.resolutionFailure.cause
+            result.resolutionFailure.cause,
+            result.resolutionFailure.hostArgument
           );
         }
         throw new Error(result.error);
@@ -1461,6 +1520,7 @@ export class SubagentExecutor {
       threadId?: string;
       parentToolCallId?: string;
       parentConfigurable?: Record<string, unknown>;
+      hostArgs?: SubagentHostArgs;
     }
   ): Promise<ResolvedSubagentConfigEntry> {
     if (isGraphSubagentConfig(config) || config.agentInputs != null) {
@@ -1489,6 +1549,9 @@ export class SubagentExecutor {
                 context.parentConfigurable == null
                   ? undefined
                   : sanitizeResolverConfigurable(context.parentConfigurable),
+              ...(context.hostArgs == null
+                ? {}
+                : { hostArgs: context.hostArgs }),
             }),
           context.childSignal
         ).then(
@@ -1937,7 +2000,7 @@ export class SubagentExecutor {
     }
     const executions: SubagentResumeExecution[] = [];
     for (const record of records) {
-      const { identity, binding, activeRun } = record.snapshot;
+      const { identity, binding, invocation, activeRun } = record.snapshot;
       if (identity == null) {
         continue;
       }
@@ -1981,6 +2044,9 @@ export class SubagentExecutor {
           ? {}
           : { subagentType: binding.subagentType }),
         ...(binding?.configId == null ? {} : { configId: binding.configId }),
+        ...(invocation?.hostArgsDigest == null
+          ? {}
+          : { hostArgsDigest: invocation.hostArgsDigest }),
         approvalExecutionScope: identity.approvalExecutionScope,
         checkpoints,
         graphState,
@@ -2333,6 +2399,22 @@ export class SubagentExecutor {
     ) {
       return;
     }
+    const resolvedHostArgsDigest =
+      settled.resolvedArgs == null
+        ? undefined
+        : getHostArgsDigestFromArgs(
+          this.configs.get(
+            resolvedSubagentType ?? execution.binding?.subagentType ?? ''
+          ),
+          settled.resolvedArgs
+        );
+    if (
+      boundInvocation != null &&
+      settled.resolvedArgs != null &&
+      resolvedHostArgsDigest !== boundInvocation.hostArgsDigest
+    ) {
+      return;
+    }
     const description =
       boundInvocation?.description ??
       resolvedDescription ??
@@ -2364,10 +2446,15 @@ export class SubagentExecutor {
       return;
     }
     const persistedOutput = serializeToolOutput(settled);
+    const hostArgsDigest =
+      settled.resolvedArgs == null
+        ? getHostArgsDigestFromArgs(executableConfig, call.args)
+        : resolvedHostArgsDigest;
     const invocation = boundInvocation ?? {
       description,
       subagentType,
       ...(configId == null ? {} : { configId }),
+      ...(hostArgsDigest == null ? {} : { hostArgsDigest }),
     };
     try {
       await execution.settle(
@@ -2484,6 +2571,15 @@ export class SubagentExecutor {
         )
       );
     }
+    const hostArgResult = resolveSubagentHostArgs(
+      executableConfig,
+      params.hostArgs
+    );
+    if (!hostArgResult.ok) {
+      return Promise.resolve(createSubagentFailure(hostArgResult.message));
+    }
+    const { hostArgs } = hostArgResult;
+    const hostArgsDigest = getSubagentHostArgsDigest(hostArgs);
     if (this.maxDepth <= 0) {
       return Promise.resolve(
         createSubagentFailure('Error: Maximum subagent nesting depth exceeded.')
@@ -2522,8 +2618,10 @@ export class SubagentExecutor {
           ...(executableConfig.configId == null
             ? {}
             : { configId: executableConfig.configId }),
+          ...(hostArgsDigest == null ? {} : { hostArgsDigest }),
         },
-        () => this.executeOnce(params, execution, executableConfig)
+        () =>
+          this.executeOnce({ ...params, hostArgs }, execution, executableConfig)
       );
     } catch (error) {
       if (error instanceof SubagentDefinitionBindingError) {
@@ -2616,8 +2714,21 @@ export class SubagentExecutor {
             : execution.address.branchChildThreadId),
         taskId: params.taskRuntime?.taskId,
       },
-      this.onResolutionFailure
+      this.onResolutionFailure,
+      params.hostArgs
     );
+    const hostArgument =
+      phase === 'config'
+        ? getSubagentHostArgumentFailure(error, params.hostArgs)
+        : undefined;
+    if (hostArgument != null) {
+      return {
+        ...createSubagentFailure(
+          getSubagentHostArgumentFailureMessage(hostArgument)
+        ),
+        resolutionFailure: { phase, cause: detail.cause, hostArgument },
+      };
+    }
     return {
       ...createSubagentFailure(detail.message),
       resolutionFailure: { phase, cause: detail.cause },
@@ -2652,6 +2763,14 @@ export class SubagentExecutor {
       this.executions.remove(execution);
       return createSubagentFailure(SUBAGENT_CONFIG_CHANGED_MESSAGE);
     }
+    if (
+      resumeExecution != null &&
+      resumeExecution.hostArgsDigest !==
+        getSubagentHostArgsDigest(params.hostArgs)
+    ) {
+      this.executions.remove(execution);
+      return createSubagentFailure(SUBAGENT_INVOCATION_CHANGED_MESSAGE);
+    }
     let identity: SubagentExecutionIdentity;
     try {
       identity = await this.resolveChildExecutionIdentity(execution);
@@ -2690,6 +2809,7 @@ export class SubagentExecutor {
         threadId,
         parentToolCallId,
         parentConfigurable: params.parentConfigurable,
+        hostArgs: params.hostArgs,
       });
       execution.assertUsable(childSignal);
     } catch (error) {
@@ -2831,6 +2951,7 @@ export class SubagentExecutor {
       langfuse: this.langfuse,
       tokenCounter: this.tokenCounter,
       streamLimits: this.streamLimits,
+      providerTextProtection: this.providerTextProtection,
       subagentScope: true,
       subagentExecutionContext: childExecutionContext,
       subagentContext: this.subagentContext,
@@ -3277,7 +3398,10 @@ export class SubagentExecutor {
        * quota for that entire interval. Trips the ENTRY-captured controller:
        * after a reset, a straggler must break its own dead run, not the
        * current one. */
-      if (error instanceof StreamLimitExceededError) {
+      if (
+        error instanceof StreamLimitExceededError ||
+        error instanceof ProviderTextProtectionError
+      ) {
         childBreaker.abort(error);
       }
       const errorMessage = truncateErrorMessage(error);
@@ -3316,7 +3440,10 @@ export class SubagentExecutor {
        * fired. Rethrown here and passed through ToolNode's error conversion,
        * so the parent run rejects with the child's limit error.
        */
-      if (error instanceof StreamLimitExceededError) {
+      if (
+        error instanceof StreamLimitExceededError ||
+        error instanceof ProviderTextProtectionError
+      ) {
         throw error;
       }
       return createSubagentFailure(

package/src/tools/subagent/SubagentReplay.ts

@@ -1,20 +1,20 @@
 import type { ToolCall, ToolMessage } from '@langchain/core/messages/tool';
 import type { RunnableConfig } from '@langchain/core/runnables';
-import type { ToolOutputReferenceState } from '@/tools/toolOutputReferences';
-import type { ToolApprovalReplaySnapshot } from '@/hooks';
 import type {
   FadingTier,
   FadingTiers,
   RunStepResumeState,
   ToolSessionContext,
 } from '@/types';
-import { isFadingTier, isLegacyFadingTier } from '@/messages/fading';
+import type { ToolOutputReferenceState } from '@/tools/toolOutputReferences';
+import type { ToolApprovalReplaySnapshot } from '@/hooks';
 import {
   attachRunStepResumeState,
   getRunStepResumeState,
   isRunStepResumeState,
   stripRunStepResumeState,
 } from '@/tools/runStepResume';
+import { isFadingTier, isLegacyFadingTier } from '@/messages/fading';
 
 export const SUBAGENT_RESUME_MANIFEST_CONFIG_KEY =
   '__librechat_subagent_resume_manifest';
@@ -35,6 +35,7 @@ const SUBAGENT_RESUME_PRIVATE_PAYLOAD_KEYS = [
   SUBAGENT_RESUME_WRAPPER_VERSION_KEY,
 ] as const;
 const MAX_RESUME_MANIFEST_DEPTH = 32;
+const HOST_ARGS_DIGEST_PATTERN = /^[a-f0-9]{64}$/;
 
 export interface SubagentCheckpointReference {
   threadId: string;
@@ -83,6 +84,8 @@ export interface SubagentResumeExecution {
   subagentType?: string;
   /** Lazy child revision bound when this execution first resolved. */
   configId?: string;
+  /** SHA-256 identity of the host arguments bound to this execution; never the values. */
+  hostArgsDigest?: string;
   approvalExecutionScope: string;
   checkpoints: SubagentCheckpointReference[];
   graphState: SubagentGraphResumeState;
@@ -354,6 +357,7 @@ function isSubagentResumeExecution(
   const childRunId = execution.childRunId;
   const subagentType = execution.subagentType;
   const configId = execution.configId;
+  const hostArgsDigest = execution.hostArgsDigest;
   const approvalExecutionScope = execution.approvalExecutionScope;
   const checkpoints = execution.checkpoints;
   const graphState = execution.graphState;
@@ -363,6 +367,9 @@ function isSubagentResumeExecution(
     !isString(childRunId) ||
     (subagentType != null && !isString(subagentType)) ||
     (configId != null && !isString(configId)) ||
+    (hostArgsDigest != null &&
+      (typeof hostArgsDigest !== 'string' ||
+        !HOST_ARGS_DIGEST_PATTERN.test(hostArgsDigest))) ||
     !isString(approvalExecutionScope) ||
     !Array.isArray(checkpoints) ||
     checkpoints.length === 0 ||

package/src/tools/subagent/childGraphConfig.ts

@@ -15,6 +15,7 @@ import {
   MAX_GRAPH_SUBAGENT_MEMBERS,
   MAX_GRAPH_SUBAGENT_TURNS,
 } from './runtimeLimits';
+import { getSubagentHostArgSpecs } from './hostArgs';
 
 const RESERVED_GRAPH_MEMBER_IDS = new Set([
   '__start__',
@@ -69,6 +70,7 @@ type GraphSubagentConfigCandidate = {
   configId?: unknown;
   agentInputs?: unknown;
   resolveAgentInputs?: unknown;
+  hostArgs?: unknown;
   self?: unknown;
 };
 
@@ -156,10 +158,11 @@ function assertGraphSubagentConfigShape(
     candidate.agentInputs !== undefined ||
     candidate.resolveAgentInputs !== undefined ||
     candidate.configId !== undefined ||
+    candidate.hostArgs !== undefined ||
     candidate.self !== undefined
   ) {
     throw new Error(
-      `Graph subagent "${configType}" cannot define agentInputs or self, or lazy fields configId/resolveAgentInputs.`
+      `Graph subagent "${configType}" cannot define agentInputs or self, or lazy fields configId/resolveAgentInputs/hostArgs.`
     );
   }
 }
@@ -482,6 +485,14 @@ function normalizeSingleAgentConfig(
       `Subagent "${config.type}" cannot combine self with resolveAgentInputs.`
     );
   }
+  if (
+    getSubagentHostArgSpecs(config).length > 0 &&
+    (config.resolveAgentInputs == null || config.agentInputs != null)
+  ) {
+    throw new Error(
+      `Subagent "${config.type}" declares hostArgs, which only a lazy resolveAgentInputs config without eager agentInputs can receive.`
+    );
+  }
   if (config.agentInputs != null) {
     return config as ResolvedSingleAgentSubagentConfig;
   }

package/src/tools/subagent/diagnostics.ts

@@ -1,3 +1,4 @@
+import type { SubagentHostArgs } from '@/types/graph';
 import {
   SubagentSettlementBindingError,
   SubagentDefinitionBindingError,
@@ -5,11 +6,39 @@ import {
   SubagentExecutionInvalidatedError,
 } from './SubagentExecutionRegistry';
 import { describeCodeApiError } from '@/tools/diagnostics';
+import { isSubagentHostArgName } from './hostArgs';
 
 /** Which step of child start-up failed: execution identity, then host config resolution. */
 export type SubagentResolutionPhase = 'identity' | 'config';
 
+/** Why a host resolver refused a declared host argument value. */
+export type SubagentHostArgumentRejection = 'unavailable' | 'not_allowed';
+
+/**
+ * Thrown by a lazy resolver to refuse one declared host argument value. The
+ * parent model receives a fixed message naming the argument; the value and
+ * any error text stay private.
+ */
+export class SubagentHostArgumentError extends Error {
+  readonly argument: string;
+  readonly rejection: SubagentHostArgumentRejection;
+
+  constructor(argument: string, rejection: SubagentHostArgumentRejection) {
+    super('Subagent host argument was rejected.');
+    this.name = 'SubagentHostArgumentError';
+    this.argument = argument;
+    this.rejection = rejection;
+  }
+}
+
+/** Safe host-argument refusal retained across the detached delivery boundary. */
+export type SubagentHostArgumentFailure = {
+  argument: string;
+  rejection: SubagentHostArgumentRejection;
+};
+
 const SUBAGENT_ERROR_TYPES = [
+  ['SubagentHostArgumentError', SubagentHostArgumentError],
   ['SubagentExecutionInvalidatedError', SubagentExecutionInvalidatedError],
   ['SubagentDefinitionBindingError', SubagentDefinitionBindingError],
   ['SubagentInvocationBindingError', SubagentInvocationBindingError],
@@ -27,6 +56,8 @@ const SUBAGENT_RESOLUTION_MESSAGES = {
   model_unavailable: 'Subagent error: Model or provider unavailable.',
   configuration_changed:
     'Subagent error: Subagent configuration changed. Start a new execution.',
+  host_argument_rejected:
+    'Subagent error: A requested subagent argument is not available. Omit it to let the host choose, or pass a different value.',
   unknown: 'Subagent error: Unable to initialize the selected subagent.',
 } as const;
 
@@ -67,6 +98,7 @@ function normalizeResolutionCause(
   case 'agent_unavailable':
   case 'model_unavailable':
   case 'configuration_changed':
+  case 'host_argument_rejected':
     return cause;
   default:
     return 'unknown';
@@ -79,16 +111,68 @@ export function getSubagentResolutionFailureMessage(
   return SUBAGENT_RESOLUTION_MESSAGES[normalizeResolutionCause(cause)];
 }
 
+/** Returns a resolver's typed host-argument refusal when its name is safe to show. */
+export function getSubagentHostArgumentFailure(
+  error: unknown,
+  suppliedHostArgs: SubagentHostArgs | undefined
+): SubagentHostArgumentFailure | undefined {
+  try {
+    if (
+      !(error instanceof SubagentHostArgumentError) ||
+      suppliedHostArgs == null
+    ) {
+      return undefined;
+    }
+    const { argument, rejection } = error;
+    if (
+      typeof argument !== 'string' ||
+      !isSubagentHostArgName(argument) ||
+      !Object.prototype.hasOwnProperty.call(suppliedHostArgs, argument)
+    ) {
+      return undefined;
+    }
+    return {
+      argument,
+      rejection: rejection === 'unavailable' ? 'unavailable' : 'not_allowed',
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/** Model-facing message for a refused host argument. */
+export function getSubagentHostArgumentFailureMessage(
+  failure: SubagentHostArgumentFailure
+): string {
+  const { argument } = failure;
+  const omit = `Omit "${argument}" to let the host choose, or pass a different value.`;
+  return failure.rejection === 'unavailable'
+    ? `Subagent error: The requested "${argument}" is unavailable right now. ${omit}`
+    : `Subagent error: The requested "${argument}" is not allowed for this subagent. ${omit}`;
+}
+
 /** Safe typed failure retained when detached execution crosses the host boundary. */
 export class SubagentResolutionError extends Error {
   readonly phase: SubagentResolutionPhase;
   readonly resolutionCause: SubagentResolutionCause;
+  readonly hostArgument?: SubagentHostArgumentFailure;
 
-  constructor(phase: SubagentResolutionPhase, cause: SubagentResolutionCause) {
-    super(getSubagentResolutionFailureMessage(cause));
+  constructor(
+    phase: SubagentResolutionPhase,
+    cause: SubagentResolutionCause,
+    hostArgument?: SubagentHostArgumentFailure
+  ) {
+    super(
+      hostArgument == null
+        ? getSubagentResolutionFailureMessage(cause)
+        : getSubagentHostArgumentFailureMessage(hostArgument)
+    );
     this.name = 'SubagentResolutionError';
     this.phase = phase;
     this.resolutionCause = normalizeResolutionCause(cause);
+    if (hostArgument != null) {
+      this.hostArgument = hostArgument;
+    }
   }
 }
 
@@ -111,7 +195,8 @@ export function logSubagentResolutionFailure(
   signal: AbortSignal,
   error: unknown,
   context?: SubagentResolutionContext,
-  onResolutionFailure?: SubagentResolutionFailureHandler
+  onResolutionFailure?: SubagentResolutionFailureHandler,
+  suppliedHostArgs?: SubagentHostArgs
 ): SubagentResolutionDiagnostic {
   const detail: SubagentResolutionDiagnostic = {
     ...context,
@@ -122,11 +207,18 @@ export function logSubagentResolutionFailure(
     cause: 'unknown',
     message: SUBAGENT_RESOLUTION_MESSAGES.unknown,
   };
+  const hostArgumentRejected =
+    getSubagentHostArgumentFailure(error, suppliedHostArgs) != null;
+  if (hostArgumentRejected) {
+    detail.cause = 'host_argument_rejected';
+    detail.message = SUBAGENT_RESOLUTION_MESSAGES.host_argument_rejected;
+  }
   if (onResolutionFailure != null) {
     try {
-      const cause = normalizeResolutionCause(
-        onResolutionFailure(Object.freeze(detail), error)
-      );
+      const reported = onResolutionFailure(Object.freeze({ ...detail }), error);
+      const cause = hostArgumentRejected
+        ? detail.cause
+        : normalizeResolutionCause(reported);
       return {
         ...detail,
         cause,