@dexto/agent-management 1.5.6 → 1.5.8

package/dist/tool-provider/llm-resolution.cjs

@@ -0,0 +1,74 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var llm_resolution_exports = {};
+__export(llm_resolution_exports, {
+  resolveSubAgentLLM: () => resolveSubAgentLLM
+});
+module.exports = __toCommonJS(llm_resolution_exports);
+var import_core = require("@dexto/core");
+function resolveSubAgentLLM(options) {
+  const { subAgentLLM, parentLLM, subAgentId } = options;
+  const agentLabel = subAgentId ? `'${subAgentId}'` : "sub-agent";
+  const subAgentProvider = subAgentLLM.provider;
+  const subAgentModel = subAgentLLM.model;
+  const parentProvider = parentLLM.provider;
+  if ((0, import_core.hasAllRegistryModelsSupport)(parentProvider)) {
+    try {
+      const transformedModel = (0, import_core.transformModelNameForProvider)(
+        subAgentModel,
+        subAgentProvider,
+        parentProvider
+      );
+      return {
+        llm: {
+          ...subAgentLLM,
+          provider: parentProvider,
+          model: transformedModel,
+          apiKey: parentLLM.apiKey,
+          baseURL: parentLLM.baseURL
+        },
+        resolution: "gateway-transform",
+        reason: `${agentLabel} using ${parentProvider} gateway with model ${transformedModel} (transformed from ${subAgentProvider}/${subAgentModel})`
+      };
+    } catch {
+    }
+  }
+  if (parentProvider === subAgentProvider) {
+    return {
+      llm: {
+        ...subAgentLLM,
+        apiKey: parentLLM.apiKey,
+        // Use parent's credentials
+        baseURL: parentLLM.baseURL
+        // Inherit custom endpoint (e.g., Azure OpenAI)
+      },
+      resolution: "same-provider",
+      reason: `${agentLabel} using ${subAgentProvider}/${subAgentModel} with parent's credentials`
+    };
+  }
+  return {
+    llm: parentLLM,
+    resolution: "parent-fallback",
+    reason: `${agentLabel} cannot use ${subAgentProvider}/${subAgentModel} with parent's ${parentProvider} provider. Falling back to parent's LLM config. Tip: Use 'dexto login' for Dexto Nova Credits which supports all models.`
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  resolveSubAgentLLM
+});

package/dist/tool-provider/llm-resolution.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Sub-agent LLM resolution logic
+ *
+ * When a parent agent spawns a sub-agent (e.g., coding-agent spawns explore-agent),
+ * this module determines which LLM configuration the sub-agent should use.
+ *
+ * Resolution priority:
+ * 1. If parent's provider can serve sub-agent's model (dexto-nova/openrouter/same provider)
+ *    → Use parent's provider + sub-agent's model (transformed if needed)
+ * 2. If incompatible providers
+ *    → Fall back to parent's full LLM config (with warning)
+ *
+ * Future enhancement (when .local.yml is implemented):
+ * 0. Check sub-agent's .local.yml for LLM override (highest priority)
+ */
+import type { LLMConfig } from '@dexto/core';
+/**
+ * Result of resolving a sub-agent's LLM configuration
+ */
+export interface SubAgentLLMResolution {
+    /** The resolved LLM configuration to use */
+    llm: LLMConfig;
+    /** How the resolution was determined */
+    resolution: 'gateway-transform' | 'same-provider' | 'parent-fallback';
+    /** Human-readable explanation for debugging */
+    reason: string;
+}
+export interface ResolveSubAgentLLMOptions {
+    /** The sub-agent's bundled LLM configuration */
+    subAgentLLM: LLMConfig;
+    /** The parent agent's LLM configuration (already has preferences applied) */
+    parentLLM: LLMConfig;
+    /** Sub-agent ID for logging purposes */
+    subAgentId?: string;
+}
+/**
+ * Resolves which LLM configuration a sub-agent should use.
+ *
+ * The goal is to use the sub-agent's intended model (e.g., Haiku for explore-agent)
+ * when possible, while leveraging the parent's provider/credentials.
+ *
+ * @example
+ * // Parent uses dexto-nova, sub-agent wants anthropic/haiku
+ * resolveSubAgentLLM({
+ *   subAgentLLM: { provider: 'anthropic', model: 'claude-haiku-4-5-20251001', apiKey: '$ANTHROPIC_API_KEY' },
+ *   parentLLM: { provider: 'dexto-nova', model: 'anthropic/claude-sonnet-4', apiKey: '$DEXTO_API_KEY' }
+ * })
+ * // Returns: { provider: 'dexto-nova', model: 'anthropic/claude-haiku-4.5', apiKey: '$DEXTO_API_KEY' }
+ */
+export declare function resolveSubAgentLLM(options: ResolveSubAgentLLMOptions): SubAgentLLMResolution;
+//# sourceMappingURL=llm-resolution.d.ts.map

package/dist/tool-provider/llm-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-resolution.d.ts","sourceRoot":"","sources":["../../src/tool-provider/llm-resolution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAClC,4CAA4C;IAC5C,GAAG,EAAE,SAAS,CAAC;IACf,wCAAwC;IACxC,UAAU,EACJ,mBAAmB,GACnB,eAAe,GACf,iBAAiB,CAAC;IACxB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,yBAAyB;IACtC,gDAAgD;IAChD,WAAW,EAAE,SAAS,CAAC;IACvB,6EAA6E;IAC7E,SAAS,EAAE,SAAS,CAAC;IACrB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,qBAAqB,CAmE5F"}

package/dist/tool-provider/llm-resolution.js

@@ -0,0 +1,50 @@
+import { hasAllRegistryModelsSupport, transformModelNameForProvider } from "@dexto/core";
+function resolveSubAgentLLM(options) {
+  const { subAgentLLM, parentLLM, subAgentId } = options;
+  const agentLabel = subAgentId ? `'${subAgentId}'` : "sub-agent";
+  const subAgentProvider = subAgentLLM.provider;
+  const subAgentModel = subAgentLLM.model;
+  const parentProvider = parentLLM.provider;
+  if (hasAllRegistryModelsSupport(parentProvider)) {
+    try {
+      const transformedModel = transformModelNameForProvider(
+        subAgentModel,
+        subAgentProvider,
+        parentProvider
+      );
+      return {
+        llm: {
+          ...subAgentLLM,
+          provider: parentProvider,
+          model: transformedModel,
+          apiKey: parentLLM.apiKey,
+          baseURL: parentLLM.baseURL
+        },
+        resolution: "gateway-transform",
+        reason: `${agentLabel} using ${parentProvider} gateway with model ${transformedModel} (transformed from ${subAgentProvider}/${subAgentModel})`
+      };
+    } catch {
+    }
+  }
+  if (parentProvider === subAgentProvider) {
+    return {
+      llm: {
+        ...subAgentLLM,
+        apiKey: parentLLM.apiKey,
+        // Use parent's credentials
+        baseURL: parentLLM.baseURL
+        // Inherit custom endpoint (e.g., Azure OpenAI)
+      },
+      resolution: "same-provider",
+      reason: `${agentLabel} using ${subAgentProvider}/${subAgentModel} with parent's credentials`
+    };
+  }
+  return {
+    llm: parentLLM,
+    resolution: "parent-fallback",
+    reason: `${agentLabel} cannot use ${subAgentProvider}/${subAgentModel} with parent's ${parentProvider} provider. Falling back to parent's LLM config. Tip: Use 'dexto login' for Dexto Nova Credits which supports all models.`
+  };
+}
+export {
+  resolveSubAgentLLM
+};

package/dist/tool-provider/runtime-service.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,22 +17,66 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var runtime_service_exports = {};
 __export(runtime_service_exports, {
   RuntimeService: () => RuntimeService
 });
 module.exports = __toCommonJS(runtime_service_exports);
+var import_core = require("@dexto/core");
 var import_AgentRuntime = require("../runtime/AgentRuntime.js");
 var import_approval_delegation = require("../runtime/approval-delegation.js");
 var import_loader = require("../config/loader.js");
 var import_registry = require("../registry/registry.js");
+var import_types = require("../registry/types.js");
+var import_path = require("../utils/path.js");
+var path = __toESM(require("path"), 1);
+var import_llm_resolution = require("./llm-resolution.js");
 class RuntimeService {
   runtime;
   parentId;
   parentAgent;
   config;
   logger;
+  resolveBundledAgentConfig(agentId) {
+    const baseDir = "agents";
+    const normalizedPath = path.relative(baseDir, path.join(baseDir, agentId));
+    if (normalizedPath.startsWith("..") || path.isAbsolute(normalizedPath)) {
+      return null;
+    }
+    const candidates = [
+      `agents/${agentId}/${agentId}.yml`,
+      `agents/${agentId}/${agentId}.yaml`,
+      `agents/${agentId}.yml`,
+      `agents/${agentId}.yaml`
+    ];
+    for (const candidate of candidates) {
+      try {
+        return (0, import_path.resolveBundledScript)(candidate);
+      } catch {
+      }
+    }
+    return null;
+  }
+  createFallbackRegistryEntry(agentId) {
+    return {
+      id: agentId,
+      name: (0, import_types.deriveDisplayName)(agentId),
+      description: "Agent specified in config (registry entry not found)",
+      author: "unknown",
+      tags: [],
+      source: agentId,
+      type: "custom"
+    };
+  }
   constructor(parentAgent, config, logger) {
     this.parentAgent = parentAgent;
     this.config = config;
@@ -69,6 +115,7 @@ class RuntimeService {
    * @param input.task - Short task description (for logging/UI)
    * @param input.instructions - Full prompt sent to sub-agent
    * @param input.agentId - Optional agent ID from registry
+   * @param input.autoApprove - Optional override for auto-approve (used by fork skills)
    * @param input.timeout - Optional task timeout in milliseconds
    * @param input.toolCallId - Optional tool call ID for progress events
    * @param input.sessionId - Optional session ID for progress events
@@ -95,10 +142,7 @@ class RuntimeService {
       }
     }
     const timeout = input.timeout ?? this.config.defaultTimeout;
-    let autoApprove = false;
-    if (input.agentId && this.config.autoApproveAgents) {
-      autoApprove = this.config.autoApproveAgents.includes(input.agentId);
-    }
+    const autoApprove = input.autoApprove !== void 0 ? input.autoApprove : !!(input.agentId && this.config.autoApproveAgents?.includes(input.agentId));
     const result = await this.trySpawnWithFallback(
       input,
       timeout,
@@ -108,6 +152,36 @@ class RuntimeService {
     );
     return result;
   }
+  /**
+   * Fork execution to an isolated subagent.
+   * Implements TaskForker interface for use by invoke_skill when context: fork is set.
+   *
+   * @param options.task - Short description for UI/logs
+   * @param options.instructions - Full instructions for the subagent
+   * @param options.agentId - Optional agent ID from registry to use for execution
+   * @param options.autoApprove - Auto-approve tool calls (default: true for fork skills)
+   * @param options.toolCallId - Optional tool call ID for progress events
+   * @param options.sessionId - Optional session ID for progress events
+   */
+  async fork(options) {
+    const spawnOptions = {
+      task: options.task,
+      instructions: options.instructions
+    };
+    if (options.agentId) {
+      spawnOptions.agentId = options.agentId;
+    }
+    if (options.autoApprove !== void 0) {
+      spawnOptions.autoApprove = options.autoApprove;
+    }
+    if (options.toolCallId) {
+      spawnOptions.toolCallId = options.toolCallId;
+    }
+    if (options.sessionId) {
+      spawnOptions.sessionId = options.sessionId;
+    }
+    return this.spawnAndExecute(spawnOptions);
+  }
   /**
    * Set up progress event emission for a sub-agent.
    * Subscribes to llm:tool-call and llm:response events and emits service:event with progress data.
@@ -183,12 +257,25 @@ class RuntimeService {
       subAgentBus.off("llm:response", responseHandler);
     };
   }
+  /**
+   * Check if an error is LLM-related (API errors, credit issues, model not found, etc.)
+   */
+  isLLMError(error) {
+    if (error instanceof import_core.DextoRuntimeError) {
+      if (error.scope === "llm") return true;
+      if (error.type === import_core.ErrorType.PAYMENT_REQUIRED || error.type === import_core.ErrorType.FORBIDDEN) {
+        return true;
+      }
+    }
+    const msg = error instanceof Error ? error.message : String(error);
+    return msg.includes("model") || msg.includes("provider") || msg.includes("rate limit") || msg.includes("quota");
+  }
   /**
    * Try to spawn agent, falling back to parent's LLM config if the sub-agent's config fails
    */
   async trySpawnWithFallback(input, timeout, autoApprove, toolCallId, sessionId) {
     let spawnedAgentId;
-    let usedFallback = false;
+    let llmMode = "subagent";
     let cleanupProgressTracking;
     try {
       const buildOptions = {};
@@ -198,7 +285,7 @@ class RuntimeService {
       if (autoApprove) {
         buildOptions.autoApprove = autoApprove;
       }
-      let subAgentConfig = await this.buildSubAgentConfig(buildOptions);
+      let subAgentConfig = await this.buildSubAgentConfig(buildOptions, sessionId);
       let handle;
       try {
         handle = await this.runtime.spawnAgent({
@@ -224,15 +311,15 @@ class RuntimeService {
         });
         spawnedAgentId = handle.agentId;
       } catch (spawnError) {
-        const errorMsg = spawnError instanceof Error ? spawnError.message : String(spawnError);
-        const isLlmError = errorMsg.includes("Model") || errorMsg.includes("model") || errorMsg.includes("API") || errorMsg.includes("apiKey") || errorMsg.includes("provider");
-        if (isLlmError && input.agentId) {
+        const isLlmError = this.isLLMError(spawnError);
+        if (isLlmError && input.agentId && llmMode === "subagent") {
+          const errorMsg = spawnError instanceof Error ? spawnError.message : String(spawnError);
           this.logger.warn(
-            `Sub-agent LLM config failed: ${errorMsg}. Falling back to parent's LLM config.`
+            `Sub-agent '${input.agentId}' LLM config failed: ${errorMsg}. Falling back to parent's full LLM config.`
           );
-          usedFallback = true;
+          llmMode = "parent";
           buildOptions.inheritLlm = true;
-          subAgentConfig = await this.buildSubAgentConfig(buildOptions);
+          subAgentConfig = await this.buildSubAgentConfig(buildOptions, sessionId);
           handle = await this.runtime.spawnAgent({
             agentConfig: subAgentConfig,
             ephemeral: true,
@@ -241,7 +328,8 @@ class RuntimeService {
               parentId: this.parentId,
               task: input.task,
               autoApprove,
-              usedLlmFallback: true,
+              llmMode: "parent",
+              fallbackStage: "spawn",
               spawnedAt: (/* @__PURE__ */ new Date()).toISOString()
             },
             onBeforeStart: (agent) => {
@@ -261,7 +349,7 @@ class RuntimeService {
         }
       }
       this.logger.info(
-        `Spawned sub-agent '${spawnedAgentId}' for task: ${input.task}${autoApprove ? " (auto-approve)" : ""}${usedFallback ? " (using parent LLM)" : ""}`
+        `Spawned sub-agent '${spawnedAgentId}' for task: ${input.task}${autoApprove ? " (auto-approve)" : ""}${llmMode === "parent" ? " (using parent LLM)" : ""}`
       );
       cleanupProgressTracking = this.setupProgressTracking(
         handle,
@@ -269,11 +357,74 @@ class RuntimeService {
         toolCallId,
         sessionId
       );
-      const result = await this.runtime.executeTask(
-        spawnedAgentId,
-        input.instructions,
-        timeout
-      );
+      let result;
+      try {
+        result = await this.runtime.executeTask(
+          spawnedAgentId,
+          input.instructions,
+          timeout
+        );
+      } catch (execError) {
+        const isLlmExecError = this.isLLMError(execError);
+        if (llmMode === "parent") {
+          throw execError;
+        }
+        if (isLlmExecError && input.agentId && llmMode === "subagent") {
+          this.logger.warn(
+            `Sub-agent '${input.agentId}' LLM error during execution: ${execError instanceof Error ? execError.message : String(execError)}. Retrying with parent's full LLM config.`
+          );
+          try {
+            await this.runtime.stopAgent(spawnedAgentId);
+          } catch {
+          }
+          if (cleanupProgressTracking) {
+            cleanupProgressTracking();
+          }
+          llmMode = "parent";
+          buildOptions.inheritLlm = true;
+          subAgentConfig = await this.buildSubAgentConfig(buildOptions, sessionId);
+          handle = await this.runtime.spawnAgent({
+            agentConfig: subAgentConfig,
+            ephemeral: true,
+            group: this.parentId,
+            metadata: {
+              parentId: this.parentId,
+              task: input.task,
+              autoApprove,
+              llmMode: "parent",
+              fallbackStage: "execution",
+              spawnedAt: (/* @__PURE__ */ new Date()).toISOString()
+            },
+            onBeforeStart: (agent) => {
+              if (!autoApprove) {
+                const delegatingHandler = (0, import_approval_delegation.createDelegatingApprovalHandler)(
+                  this.parentAgent.services.approvalManager,
+                  agent.config.agentId ?? "unknown",
+                  this.logger
+                );
+                agent.setApprovalHandler(delegatingHandler);
+              }
+            }
+          });
+          spawnedAgentId = handle.agentId;
+          this.logger.info(
+            `Re-spawned sub-agent '${spawnedAgentId}' for task: ${input.task} (using parent LLM)`
+          );
+          cleanupProgressTracking = this.setupProgressTracking(
+            handle,
+            input,
+            toolCallId,
+            sessionId
+          );
+          result = await this.runtime.executeTask(
+            spawnedAgentId,
+            input.instructions,
+            timeout
+          );
+        } else {
+          throw execError;
+        }
+      }
       const output = {
         success: result.success
       };
@@ -283,6 +434,9 @@ class RuntimeService {
       if (result.error !== void 0) {
         output.error = result.error;
       }
+      if (llmMode === "parent") {
+        output.warning = `Sub-agent '${input.agentId}' used fallback LLM (parent's full config) due to an error with its configured model.`;
+      }
       return output;
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
@@ -309,24 +463,56 @@ class RuntimeService {
    * @param options.agentId - Agent ID from registry
    * @param options.inheritLlm - Use parent's LLM config instead of sub-agent's
    * @param options.autoApprove - Auto-approve all tool calls
+   * @param sessionId - Optional session ID to get session-specific LLM config
    */
-  async buildSubAgentConfig(options) {
+  async buildSubAgentConfig(options, sessionId) {
     const { agentId, inheritLlm, autoApprove } = options;
     const parentConfig = this.parentAgent.config;
+    const currentParentLLM = this.parentAgent.getCurrentLLMConfig(sessionId);
+    this.logger.debug(
+      `[RuntimeService] Building sub-agent config with LLM: ${currentParentLLM.provider}/${currentParentLLM.model}` + (sessionId ? ` (sessionId: ${sessionId})` : " (no sessionId)")
+    );
     const toolConfirmationMode = autoApprove ? "auto-approve" : "manual";
     if (agentId) {
-      const registry = (0, import_registry.getAgentRegistry)();
-      if (!registry.hasAgent(agentId)) {
-        this.logger.warn(`Agent '${agentId}' not found in registry. Using default config.`);
-      } else {
-        const configPath = await registry.resolveAgent(agentId);
-        this.logger.debug(`Loading agent config from registry: ${configPath}`);
+      let configPath = null;
+      try {
+        const registry = (0, import_registry.getAgentRegistry)();
+        if (!registry.hasAgent(agentId)) {
+          this.logger.warn(
+            `Agent '${agentId}' not found in registry. Trying bundled config paths.`
+          );
+        } else {
+          configPath = await registry.resolveAgent(agentId);
+        }
+      } catch (error) {
+        this.logger.warn(
+          `Failed to load agent registry for '${agentId}'. Trying bundled config paths. (${error instanceof Error ? error.message : String(error)})`
+        );
+      }
+      if (!configPath) {
+        configPath = this.resolveBundledAgentConfig(agentId);
+      }
+      if (configPath) {
+        this.logger.debug(`Loading agent config from registry/bundled path: ${configPath}`);
         const loadedConfig = await (0, import_loader.loadAgentConfig)(configPath, this.logger);
         let llmConfig = loadedConfig.llm;
         if (inheritLlm) {
-          this.logger.debug("Using parent LLM config (inheritLlm=true)");
-          llmConfig = { ...parentConfig.llm };
+          this.logger.debug(
+            `Sub-agent '${agentId}' using parent LLM config (inheritLlm=true)`
+          );
+          llmConfig = { ...currentParentLLM };
+        } else {
+          const resolution = (0, import_llm_resolution.resolveSubAgentLLM)({
+            subAgentLLM: loadedConfig.llm,
+            parentLLM: currentParentLLM,
+            subAgentId: agentId
+          });
+          this.logger.debug(`Sub-agent LLM resolution: ${resolution.reason}`);
+          llmConfig = resolution.llm;
         }
+        const filteredCustomTools = loadedConfig.customTools ? loadedConfig.customTools.filter(
+          (tool) => typeof tool === "object" && tool !== null && "type" in tool && tool.type !== "agent-spawner"
+        ) : void 0;
         return {
           ...loadedConfig,
           llm: llmConfig,
@@ -334,6 +520,7 @@ class RuntimeService {
             ...loadedConfig.toolConfirmation,
             mode: toolConfirmationMode
           },
+          customTools: filteredCustomTools,
           // Suppress sub-agent console logs entirely using silent transport
           logger: {
             level: "error",
@@ -341,14 +528,30 @@ class RuntimeService {
           }
         };
       }
+      this.logger.warn(
+        `Agent '${agentId}' not found in registry or bundled paths. Using default config.`
+      );
     }
     const config = {
-      llm: { ...parentConfig.llm },
+      llm: { ...currentParentLLM },
       // Default system prompt for sub-agents
       systemPrompt: "You are a helpful sub-agent. Complete the task given to you efficiently and concisely.",
       toolConfirmation: {
         mode: toolConfirmationMode
       },
+      // Inherit MCP servers from parent so subagent has tool access
+      mcpServers: parentConfig.mcpServers ? { ...parentConfig.mcpServers } : {},
+      // Inherit internal tools from parent, excluding tools that don't work in subagent context
+      // - ask_user: Subagents can't interact with the user directly
+      // - invoke_skill: Avoid nested skill invocations for simplicity
+      internalTools: parentConfig.internalTools ? parentConfig.internalTools.filter(
+        (tool) => tool !== "ask_user" && tool !== "invoke_skill"
+      ) : [],
+      // Inherit custom tools from parent, excluding agent-spawner to prevent nested spawning (depth=1 limit)
+      // - agent-spawner: Sub-agents should not spawn their own sub-agents
+      customTools: parentConfig.customTools ? parentConfig.customTools.filter(
+        (tool) => typeof tool === "object" && tool !== null && "type" in tool && tool.type !== "agent-spawner"
+      ) : [],
       // Suppress sub-agent console logs entirely using silent transport
       logger: {
         level: "error",
@@ -362,15 +565,24 @@ class RuntimeService {
    * Returns agent metadata from registry, filtered by allowedAgents if configured.
    */
   getAvailableAgents() {
-    const registry = (0, import_registry.getAgentRegistry)();
-    const allAgents = registry.getAvailableAgents();
+    let allAgents;
+    try {
+      const registry = (0, import_registry.getAgentRegistry)();
+      allAgents = registry.getAvailableAgents();
+    } catch (error) {
+      this.logger.warn(
+        `Failed to load agent registry for spawn_agent description: ${error instanceof Error ? error.message : String(error)}`
+      );
+      if (this.config.allowedAgents && this.config.allowedAgents.length > 0) {
+        return this.config.allowedAgents.map((id) => this.createFallbackRegistryEntry(id));
+      }
+      return [];
+    }
     if (this.config.allowedAgents && this.config.allowedAgents.length > 0) {
       const result = [];
       for (const id of this.config.allowedAgents) {
         const agent = allAgents[id];
-        if (agent) {
-          result.push(agent);
-        }
+        result.push(agent ?? this.createFallbackRegistryEntry(id));
       }
       return result;
     }