@cognipeer/agent-sdk 0.7.2 → 0.8.0

package/dist/index.mjs

@@ -2573,6 +2573,27 @@ function validateToolArgs(tool, args) {
   }
 }
 
+// src/utils/pendingToolCalls.ts
+function selectPendingToolCalls(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) return [];
+  const last = messages[messages.length - 1];
+  if (last?.role === "assistant") {
+    return Array.isArray(last.tool_calls) ? last.tool_calls : [];
+  }
+  const resolvedIds = /* @__PURE__ */ new Set();
+  for (const m of messages) {
+    if (m?.role === "tool" && m.tool_call_id != null) resolvedIds.add(String(m.tool_call_id));
+  }
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const m = messages[i];
+    if (m?.role !== "assistant") continue;
+    const calls = Array.isArray(m.tool_calls) ? m.tool_calls : [];
+    if (calls.length === 0) return [];
+    return calls.filter((c) => c?.id == null || !resolvedIds.has(String(c.id)));
+  }
+  return [];
+}
+
 // src/nodes/tools.ts
 function normalizeMaxExecutionsPerRun(value) {
   if (value === null || value === void 0 || value === "") return null;
@@ -2730,9 +2751,8 @@ function createToolsNode(initialTools, opts) {
         anyTool._stateRef.parentRuntime = runtime;
       }
     }
-    const last = state.messages[state.messages.length - 1];
     let toolCount = state.toolCallCount || 0;
-    const toolCalls = Array.isArray(last?.tool_calls) ? last.tool_calls.map((toolCall) => normalizeToolCall(toolCall)).filter((toolCall) => toolCall !== null) : [];
+    const toolCalls = selectPendingToolCalls(state.messages).map((toolCall) => normalizeToolCall(toolCall)).filter((toolCall) => toolCall !== null);
     const toolHistory = state.toolHistory || [];
     const toolHistoryArchived = state.toolHistoryArchived || [];
     const remaining = Math.max(0, limits.maxToolCalls - toolCount);
@@ -3974,12 +3994,20 @@ function resolveUserQuestionState(state, resolution) {
   entry.notes = resolution.notes;
   entry.answeredAt = (/* @__PURE__ */ new Date()).toISOString();
   pending[matchIndex] = entry;
+  const isSubagentQuestion = Boolean(entry.metadata?.__subagent);
   const ctx = { ...state.ctx || {} };
   delete ctx.__awaitingUserQuestion;
-  if (ctx.__resumeStage === "tools") {
+  if (ctx.__resumeStage === "tools" && !isSubagentQuestion) {
     delete ctx.__resumeStage;
   }
   ctx.__userQuestionResolved = { id: entry.id, status: entry.status };
+  if (isSubagentQuestion) {
+    return {
+      ...state,
+      pendingUserQuestions: pending,
+      ctx
+    };
+  }
   const toolMessage = {
     role: "tool",
     name: "ask_user_question",
@@ -4260,6 +4288,88 @@ var StructuredOutputManager = class {
   }
 };
 
+// src/smart/subagents/registry.ts
+function findSubagent(subagents, name) {
+  return subagents.find((entry) => entry.name === name);
+}
+async function resolveAvailableSubagents(subagents) {
+  const out = [];
+  for (const entry of subagents) {
+    const available = entry.isAvailable ? await entry.isAvailable() : true;
+    if (available) out.push(entry);
+  }
+  return out;
+}
+function canSpawn(ref, policy, count = 1) {
+  if (policy.mode === "off") {
+    return { ok: false, reason: "sub-agents are disabled by runtime policy" };
+  }
+  if (ref.spawnedCount + count > policy.maxChildCalls) {
+    return {
+      ok: false,
+      reason: `child-call budget exhausted (${policy.maxChildCalls}); ${ref.spawnedCount} already spawned`
+    };
+  }
+  return { ok: true };
+}
+function withinDepth(currentDepth, policy) {
+  if (currentDepth >= policy.maxDepth) {
+    return { ok: false, reason: `delegation depth limit reached (${policy.maxDepth})` };
+  }
+  return { ok: true };
+}
+function seedChildMessages(policy, parentMessages, input) {
+  const messages = (Array.isArray(parentMessages) ? parentMessages : []).filter((m) => m?.role !== "system");
+  switch (policy) {
+    case "full":
+      return [...messages, { role: "user", content: input }];
+    case "scoped": {
+      const lastUser = [...messages].reverse().find((m) => m?.role === "user");
+      return [
+        ...lastUser ? [lastUser] : [],
+        { role: "user", content: input }
+      ];
+    }
+    case "minimal":
+    default:
+      return [{ role: "user", content: input }];
+  }
+}
+async function resolveSubagentTools(declared, parentTools) {
+  if (!declared) return [];
+  if (typeof declared === "function") {
+    return await declared();
+  }
+  if (Array.isArray(declared) && declared.length > 0 && typeof declared[0] === "string") {
+    const wanted = new Set(declared);
+    return parentTools.filter((tool) => wanted.has(tool?.name));
+  }
+  return declared;
+}
+function buildSubagentCatalogBlock(subagents, policy, toolNames) {
+  const lines = ["<available_subagents>"];
+  const adhoc = policy.mode === "registry_and_adhoc";
+  lines.push(
+    "Delegate self-contained subtasks to focused sub-agents. Each runs with an isolated context and returns a concise result. Use them to decompose hard problems; do NOT delegate trivial steps you can do directly."
+  );
+  if (subagents.length > 0) {
+    lines.push(`Call ${toolNames.delegate}(subagent, input) for a named sub-agent:`);
+    for (const entry of subagents) {
+      lines.push(`- ${entry.name}: ${entry.header}`);
+    }
+  }
+  if (adhoc) {
+    lines.push(
+      `Call ${toolNames.spawn}({ role, prompt, input, tools? }) to create a sub-agent on the fly.`
+    );
+  }
+  lines.push(
+    `Call ${toolNames.parallel}({ tasks: [...] }) to run up to ${policy.maxParallel} independent subtasks concurrently (no human-input tools inside parallel children).`
+  );
+  lines.push("</available_subagents>");
+  return lines.join("\n");
+}
+
 // src/agent.ts
 function getLastAssistantMessage(messages) {
   for (let index = messages.length - 1; index >= 0; index -= 1) {
@@ -4631,7 +4741,7 @@ function createAgent(opts) {
         resumeStage = null;
       }
       const lastMsg = state.messages[state.messages.length - 1];
-      const toolCalls = Array.isArray(lastMsg?.tool_calls) ? lastMsg.tool_calls : [];
+      const toolCalls = selectPendingToolCalls(state.messages);
       const toolCallCount = state.toolCallCount || 0;
       if (state.ctx?.__finalizedDueToToolLimit) {
         break;
@@ -4931,27 +5041,28 @@ function createAgent(opts) {
               error: `Child-call budget exhausted (${delegationPolicy.maxChildCalls}).`
             };
           }
-          let childMessages;
-          switch (delegationPolicy.childContextPolicy) {
-            case "full":
-              childMessages = [...parentMessages, { role: "user", content: input }];
-              break;
-            case "scoped": {
-              const systemPrefix = parentMessages[0]?.role === "system" ? [parentMessages[0]] : [];
-              const lastUser = [...parentMessages].reverse().find((m) => m?.role === "user");
-              childMessages = [
-                ...systemPrefix,
-                ...lastUser ? [lastUser] : [],
-                { role: "user", content: input }
-              ];
-              break;
-            }
-            case "minimal":
-            default:
-              childMessages = [{ role: "user", content: input }];
-          }
+          const childMessages = seedChildMessages(
+            delegationPolicy.childContextPolicy,
+            parentMessages,
+            input
+          );
           const childCtx = { __delegationDepth: currentDepth + 1 };
-          const res = await instance.invoke({ messages: childMessages, ctx: childCtx });
+          const childConfig = {
+            onEvent: parentCtx.__onEvent ? (e) => {
+              if (e?.type === "finalAnswer" || e?.type === "metadata") return;
+              try {
+                parentCtx.__onEvent({ ...e, delegatedTo: opts.name });
+              } catch {
+              }
+            } : void 0,
+            onProgress: parentCtx.__onProgress,
+            onStream: parentCtx.__streaming && parentCtx.__onStream ? (chunk) => {
+              if (!chunk?.isFinal) parentCtx.__onStream(chunk);
+            } : void 0,
+            stream: Boolean(parentCtx.__streaming),
+            cancellationToken: parentCtx.__cancellationToken ?? parentCtx.__abortSignal
+          };
+          const res = await instance.invoke({ messages: childMessages, ctx: childCtx }, childConfig);
           return {
             content: res.content,
             output: res.output,
@@ -6378,6 +6489,421 @@ function createSkillTools(deps) {
   return [createOpenSkillTool(deps), createBindSkillToolsTool(deps)];
 }
 
+// src/smart/subagents/types.ts
+var DEFAULT_SUBAGENT_POLICY = {
+  mode: "registry_and_adhoc",
+  maxDepth: 2,
+  maxChildCalls: 8,
+  maxParallel: 4,
+  childContextPolicy: "scoped",
+  allowAdhocTools: true
+};
+function createSubagentRegistryRef() {
+  return { spawnedCount: 0, results: [] };
+}
+var DEFAULT_SUBAGENT_TOOL_NAMES = {
+  delegate: "delegate_to",
+  spawn: "spawn_subagent",
+  parallel: "spawn_subagents_parallel"
+};
+var DEFAULT_DELEGATE_DESCRIPTION = "Delegate a self-contained subtask to a predefined sub-agent. Pass the sub-agent name (from <available_subagents>) and a complete, standalone `input` describing the task and the expected result. The sub-agent runs in isolation and returns a concise result.";
+var DEFAULT_SPAWN_DESCRIPTION = "Create a sub-agent on the fly. Provide a short `role`, a `prompt` defining how it should behave, and a complete `input` task. Optionally pass `tools` (names of the parent's tools the sub-agent may use). Use for one-off specialist subtasks.";
+var DEFAULT_PARALLEL_DESCRIPTION = "Run several independent subtasks concurrently. Each task is either a registry `subagent` + `input`, or an ad-hoc `role` + `prompt` + `input`. Returns one result per task in order. Do NOT use for tasks that require human input (approval / questions).";
+var CTX_CALLBACK_KEYS = /* @__PURE__ */ new Set([
+  "__onEvent",
+  "__onProgress",
+  "__onStream",
+  "__traceSession",
+  "__paused",
+  "__cancellationToken",
+  "__abortSignal",
+  "__deadline"
+]);
+function cleanChildState(state) {
+  const { agent: _agent, ctx, ...rest } = state;
+  let cleanCtx2;
+  if (ctx && typeof ctx === "object") {
+    cleanCtx2 = {};
+    for (const [k, v] of Object.entries(ctx)) {
+      if (CTX_CALLBACK_KEYS.has(k)) continue;
+      cleanCtx2[k] = v;
+    }
+  }
+  return { ...rest, ctx: cleanCtx2 };
+}
+function makeChildEventForwarder(parentOnEvent, spawnId, name) {
+  return (event) => {
+    if (!parentOnEvent) return;
+    if (event?.type === "finalAnswer" || event?.type === "metadata") return;
+    try {
+      parentOnEvent({ ...event, subagentId: spawnId, subagentName: name });
+    } catch {
+    }
+  };
+}
+function buildChildConfig(parentCtx, spawnId, name) {
+  const streaming = Boolean(parentCtx.__streaming);
+  const parentOnStream = parentCtx.__onStream;
+  return {
+    onEvent: makeChildEventForwarder(parentCtx.__onEvent, spawnId, name),
+    onProgress: parentCtx.__onProgress,
+    // Forward streaming deltas but swallow the child's `isFinal` chunk so the
+    // host does not mistake a child completion for the parent's final answer.
+    onStream: streaming && parentOnStream ? (chunk) => {
+      if (!chunk.isFinal) parentOnStream(chunk);
+    } : void 0,
+    stream: streaming,
+    cancellationToken: parentCtx.__cancellationToken ?? parentCtx.__abortSignal
+  };
+}
+function summaryOf(state) {
+  const summaries = state?.summaries;
+  return Array.isArray(summaries) && summaries.length > 0 ? summaries[summaries.length - 1] : void 0;
+}
+async function runChild(spec, input, deps, ref, opts) {
+  const parentCtx = ref.ctx || {};
+  const parentOnEvent = parentCtx.__onEvent;
+  const spawnId = `sa_${nanoid(6)}`;
+  const start = Date.now();
+  const child = deps.buildChild({
+    name: spec.name,
+    model: spec.model,
+    systemPrompt: spec.systemPrompt,
+    tools: spec.tools,
+    outputSchema: spec.outputSchema,
+    limits: spec.limits
+  });
+  const childConfig = buildChildConfig(parentCtx, spawnId, spec.name);
+  let childInput;
+  if (opts.isResume && opts.record) {
+    const restored = { ...opts.record.childState };
+    if (opts.record.pendingKind === "approval") {
+      const entry = (ref.pendingApprovals || []).find((e) => e.id === opts.record.pendingId);
+      if (!entry) {
+        return { kind: "result", result: { name: spec.name, mode: spec.mode, input, error: "Pending approval resolution missing on resume." } };
+      }
+      if (entry.status === "pending") {
+        if (!parentCtx.__awaitingApproval) {
+          parentCtx.__awaitingApproval = { approvalId: entry.id, toolCallId: entry.toolCallId, toolName: entry.toolName, requestedAt: entry.requestedAt };
+        }
+        parentCtx.__resumeStage = "tools";
+        return { kind: "approval", toolCallId: entry.toolCallId, approvalId: entry.id };
+      }
+      childInput = resolveToolApprovalState(restored, {
+        id: opts.record.pendingId,
+        approved: entry.status === "approved",
+        approvedArgs: entry.approvedArgs,
+        decidedBy: entry.decidedBy,
+        comment: entry.comment
+      });
+    } else {
+      const entry = (ref.pendingUserQuestions || []).find((e) => e.id === opts.record.pendingId);
+      if (!entry) {
+        return { kind: "result", result: { name: spec.name, mode: spec.mode, input, error: "Pending question resolution missing on resume." } };
+      }
+      if (entry.status === "pending") {
+        if (!parentCtx.__awaitingUserQuestion) {
+          parentCtx.__awaitingUserQuestion = { id: entry.id, toolCallId: entry.toolCallId, requestedAt: entry.requestedAt };
+        }
+        parentCtx.__resumeStage = "tools";
+        return { kind: "user_question", toolCallId: entry.toolCallId, id: entry.id };
+      }
+      childInput = resolveUserQuestionState(restored, {
+        id: opts.record.pendingId,
+        answers: entry.answers,
+        answeredBy: entry.answeredBy,
+        notes: entry.notes,
+        cancelled: entry.cancelled === true
+      });
+    }
+  } else {
+    parentOnEvent?.({ type: "subagent", phase: "start", name: spec.name, id: spawnId, mode: spec.mode, parallel: opts.parallel, parentToolCallId: opts.parentToolCallId, input });
+    const currentDepth = Number(parentCtx.__delegationDepth) || 0;
+    childInput = {
+      messages: seedChildMessages(spec.childContextPolicy, ref.messages || [], input),
+      ctx: { __delegationDepth: currentDepth + 1 }
+    };
+  }
+  let res;
+  try {
+    res = await child.invoke(childInput, childConfig);
+  } catch (err) {
+    const result2 = { name: spec.name, mode: spec.mode, input, error: err?.message || String(err), durationMs: Date.now() - start };
+    deps.registryRef.results.push(result2);
+    parentOnEvent?.({ type: "subagent", phase: "error", name: spec.name, id: spawnId, mode: spec.mode, error: { message: result2.error }, parentToolCallId: opts.parentToolCallId });
+    return { kind: "result", result: result2 };
+  }
+  const childState = res.state;
+  const awaitingApproval = childState?.ctx?.__awaitingApproval;
+  const awaitingQuestion = childState?.ctx?.__awaitingUserQuestion;
+  if (childState && (awaitingApproval || awaitingQuestion)) {
+    if (!opts.allowHITL) {
+      const result2 = {
+        name: spec.name,
+        mode: spec.mode,
+        input,
+        error: "Sub-agent requested human input, which is not supported inside parallel fan-out. Run it via delegate_to / spawn_subagent instead.",
+        durationMs: Date.now() - start
+      };
+      deps.registryRef.results.push(result2);
+      return { kind: "result", result: result2 };
+    }
+    const pendingStore = parentCtx.__subagentPending || (parentCtx.__subagentPending = {});
+    if (awaitingApproval) {
+      const childEntry = (childState.pendingApprovals || []).find((e) => e.status === "pending");
+      if (childEntry) {
+        const surfaced = { ...childEntry, metadata: { ...childEntry.metadata || {}, __subagent: { parentToolCallId: opts.parentToolCallId, name: spec.name } } };
+        (ref.pendingApprovals || (ref.pendingApprovals = [])).push(surfaced);
+        if (!parentCtx.__awaitingApproval && !parentCtx.__awaitingUserQuestion) {
+          parentCtx.__awaitingApproval = { approvalId: surfaced.id, toolCallId: surfaced.toolCallId, toolName: surfaced.toolName, requestedAt: surfaced.requestedAt };
+        }
+        parentCtx.__resumeStage = "tools";
+        pendingStore[opts.parentToolCallId] = {
+          parentToolCallId: opts.parentToolCallId,
+          name: spec.name,
+          mode: spec.mode,
+          adhoc: spec.adhoc,
+          input,
+          childState: cleanChildState(childState),
+          pendingKind: "approval",
+          pendingId: childEntry.id
+        };
+        parentOnEvent?.({ type: "subagent", phase: "paused", name: spec.name, id: spawnId, mode: spec.mode, parentToolCallId: opts.parentToolCallId });
+        return { kind: "approval", toolCallId: surfaced.toolCallId, approvalId: surfaced.id };
+      }
+    }
+    if (awaitingQuestion) {
+      const childEntry = (childState.pendingUserQuestions || []).find((e) => e.status === "pending");
+      if (childEntry) {
+        const surfaced = { ...childEntry, metadata: { ...childEntry.metadata || {}, __subagent: { parentToolCallId: opts.parentToolCallId, name: spec.name } } };
+        (ref.pendingUserQuestions || (ref.pendingUserQuestions = [])).push(surfaced);
+        if (!parentCtx.__awaitingUserQuestion && !parentCtx.__awaitingApproval) {
+          parentCtx.__awaitingUserQuestion = { id: surfaced.id, toolCallId: surfaced.toolCallId, requestedAt: surfaced.requestedAt };
+        }
+        parentCtx.__resumeStage = "tools";
+        pendingStore[opts.parentToolCallId] = {
+          parentToolCallId: opts.parentToolCallId,
+          name: spec.name,
+          mode: spec.mode,
+          adhoc: spec.adhoc,
+          input,
+          childState: cleanChildState(childState),
+          pendingKind: "user_question",
+          pendingId: childEntry.id
+        };
+        parentOnEvent?.({ type: "subagent", phase: "paused", name: spec.name, id: spawnId, mode: spec.mode, parentToolCallId: opts.parentToolCallId });
+        return { kind: "user_question", toolCallId: surfaced.toolCallId, id: surfaced.id };
+      }
+    }
+  }
+  if (parentCtx.__subagentPending?.[opts.parentToolCallId]) {
+    delete parentCtx.__subagentPending[opts.parentToolCallId];
+  }
+  const result = {
+    name: spec.name,
+    mode: spec.mode,
+    input,
+    content: res.content,
+    output: res.output,
+    summary: summaryOf(childState),
+    durationMs: Date.now() - start
+  };
+  deps.registryRef.results.push(result);
+  parentOnEvent?.({ type: "subagent", phase: "result", name: spec.name, id: spawnId, mode: spec.mode, content: res.content, durationMs: result.durationMs, parentToolCallId: opts.parentToolCallId });
+  return { kind: "result", result };
+}
+async function specFromRegistry(def, deps, parentRuntime) {
+  const tools = await resolveSubagentTools(def.tools, parentRuntime?.tools || []);
+  return {
+    name: def.name,
+    mode: "registry",
+    systemPrompt: def.systemPrompt,
+    model: def.model ?? parentRuntime?.model,
+    tools,
+    outputSchema: def.outputSchema,
+    limits: def.limits,
+    childContextPolicy: def.childContextPolicy ?? deps.policy.childContextPolicy,
+    metadata: def.metadata
+  };
+}
+async function specFromAdhoc(args, deps, parentRuntime) {
+  const toolNames = deps.policy.allowAdhocTools ? args.tools ?? args.toolNames ?? [] : [];
+  const tools = await resolveSubagentTools(toolNames, parentRuntime?.tools || []);
+  const systemPrompt = [args.prompt, args.outputContract ? `Output contract: ${args.outputContract}` : ""].filter(Boolean).join("\n\n");
+  return {
+    name: args.role,
+    mode: "adhoc",
+    systemPrompt: systemPrompt || void 0,
+    model: parentRuntime?.model,
+    tools,
+    childContextPolicy: deps.policy.childContextPolicy,
+    adhoc: { role: args.role, prompt: args.prompt, toolNames, outputContract: args.outputContract }
+  };
+}
+function toToolReturn(outcome) {
+  if (outcome.kind === "approval") {
+    return { __awaitingToolApproval: true, toolCallId: outcome.toolCallId, approvalId: outcome.approvalId };
+  }
+  if (outcome.kind === "user_question") {
+    return { __awaitingUserQuestion: true, toolCallId: outcome.toolCallId, id: outcome.id };
+  }
+  return outcome.result;
+}
+function createDelegateTool(deps) {
+  const names = deps.subagents.map((s) => s.name);
+  const tool = createTool({
+    name: "delegate_to",
+    description: deps.descriptions?.delegate ?? DEFAULT_DELEGATE_DESCRIPTION,
+    schema: z.object({
+      subagent: (names.length > 0 ? z.enum(names) : z.string().min(1)).describe("Name of a sub-agent from <available_subagents>."),
+      input: z.string().min(1).describe("Complete, standalone task for the sub-agent.")
+    }).strict(),
+    func: async ({ subagent, input }) => {
+      const ref = tool._stateRef || {};
+      const d = tool._deps;
+      const parentRuntime = ref.parentRuntime;
+      const parentToolCallId = ref.__currentToolCallId || `delegate_${nanoid(6)}`;
+      const parentCtx = ref.ctx || (ref.ctx = {});
+      const def = findSubagent(d.subagents, subagent);
+      if (!def) return { error: `Unknown sub-agent: ${subagent}. Choose one from <available_subagents>.` };
+      if (def.isAvailable && !await def.isAvailable()) return { error: `Sub-agent ${subagent} is not available right now.` };
+      const record = parentCtx.__subagentPending?.[parentToolCallId];
+      const spec = await specFromRegistry(def, d, parentRuntime);
+      if (!record) {
+        const depth = withinDepth(Number(parentCtx.__delegationDepth) || 0, d.policy);
+        if (!depth.ok) return { error: depth.reason };
+        const budget = canSpawn(d.registryRef, d.policy, 1);
+        if (!budget.ok) return { error: budget.reason };
+        d.registryRef.spawnedCount += 1;
+      }
+      return toToolReturn(await runChild(spec, record?.input ?? input, d, ref, { allowHITL: true, parentToolCallId, isResume: !!record, record }));
+    }
+  });
+  tool._deps = deps;
+  tool._stateRef = {};
+  tool.__source = "smart-subagents";
+  return tool;
+}
+function createSpawnTool(deps) {
+  const tool = createTool({
+    name: "spawn_subagent",
+    description: deps.descriptions?.spawn ?? DEFAULT_SPAWN_DESCRIPTION,
+    schema: z.object({
+      role: z.string().min(1).describe("Short role name, e.g. 'db-analyst'."),
+      prompt: z.string().optional().describe("System prompt defining how the sub-agent behaves."),
+      input: z.string().min(1).describe("Complete, standalone task for the sub-agent."),
+      tools: z.array(z.string().min(1)).optional().describe("Names of the parent's tools the sub-agent may use."),
+      outputContract: z.string().optional().describe("Optional description of the expected output shape.")
+    }).strict(),
+    func: async (args) => {
+      const ref = tool._stateRef || {};
+      const d = tool._deps;
+      if (d.policy.mode !== "registry_and_adhoc") {
+        return { error: "Ad-hoc sub-agents are disabled (subagentPolicy.mode is not 'registry_and_adhoc'). Use delegate_to." };
+      }
+      const parentRuntime = ref.parentRuntime;
+      const parentToolCallId = ref.__currentToolCallId || `spawn_${nanoid(6)}`;
+      const parentCtx = ref.ctx || (ref.ctx = {});
+      const record = parentCtx.__subagentPending?.[parentToolCallId];
+      const spec = record?.adhoc ? await specFromAdhoc(record.adhoc, d, parentRuntime) : await specFromAdhoc(args, d, parentRuntime);
+      if (!record) {
+        const depth = withinDepth(Number(parentCtx.__delegationDepth) || 0, d.policy);
+        if (!depth.ok) return { error: depth.reason };
+        const budget = canSpawn(d.registryRef, d.policy, 1);
+        if (!budget.ok) return { error: budget.reason };
+        d.registryRef.spawnedCount += 1;
+      }
+      return toToolReturn(await runChild(spec, record?.input ?? args.input, d, ref, { allowHITL: true, parentToolCallId, isResume: !!record, record }));
+    }
+  });
+  tool._deps = deps;
+  tool._stateRef = {};
+  tool.__source = "smart-subagents";
+  return tool;
+}
+function createParallelTool(deps) {
+  const tool = createTool({
+    name: "spawn_subagents_parallel",
+    description: deps.descriptions?.parallel ?? DEFAULT_PARALLEL_DESCRIPTION,
+    schema: z.object({
+      tasks: z.array(
+        z.object({
+          subagent: z.string().optional().describe("Registry sub-agent name."),
+          role: z.string().optional().describe("Ad-hoc role (when not using `subagent`)."),
+          prompt: z.string().optional(),
+          tools: z.array(z.string().min(1)).optional(),
+          input: z.string().min(1)
+        }).strict()
+      ).min(1).max(16).describe("Independent subtasks to run concurrently.")
+    }).strict(),
+    func: async ({ tasks }) => {
+      const ref = tool._stateRef || {};
+      const d = tool._deps;
+      const parentRuntime = ref.parentRuntime;
+      const parentToolCallId = ref.__currentToolCallId || `parallel_${nanoid(6)}`;
+      const parentCtx = ref.ctx || (ref.ctx = {});
+      const depth = withinDepth(Number(parentCtx.__delegationDepth) || 0, d.policy);
+      if (!depth.ok) return { error: depth.reason };
+      const specs = [];
+      for (const task of tasks) {
+        if (task.subagent) {
+          const def = findSubagent(d.subagents, task.subagent);
+          if (!def) {
+            specs.push({ error: `Unknown sub-agent: ${task.subagent}`, input: task.input });
+            continue;
+          }
+          specs.push({ spec: await specFromRegistry(def, d, parentRuntime), input: task.input });
+        } else if (task.role) {
+          if (d.policy.mode !== "registry_and_adhoc") {
+            specs.push({ error: "Ad-hoc sub-agents are disabled.", input: task.input });
+            continue;
+          }
+          specs.push({ spec: await specFromAdhoc({ role: task.role, prompt: task.prompt, tools: task.tools }, d, parentRuntime), input: task.input });
+        } else {
+          specs.push({ error: "Each task needs either `subagent` or `role`.", input: task.input });
+        }
+      }
+      const spawnCount = specs.filter((entry) => !("error" in entry)).length;
+      const budget = canSpawn(d.registryRef, d.policy, spawnCount);
+      if (!budget.ok) return { error: budget.reason };
+      d.registryRef.spawnedCount += spawnCount;
+      const results = new Array(specs.length);
+      const concurrency = Math.max(1, Math.min(d.policy.maxParallel, specs.length));
+      let cursor = 0;
+      const worker = async () => {
+        while (true) {
+          const i = cursor++;
+          if (i >= specs.length) return;
+          const entry = specs[i];
+          if ("error" in entry) {
+            results[i] = { name: "?", mode: "adhoc", input: entry.input, error: entry.error };
+            continue;
+          }
+          const outcome = await runChild(entry.spec, entry.input, d, ref, {
+            allowHITL: false,
+            parentToolCallId: `${parentToolCallId}#${i}`,
+            parallel: true
+          });
+          results[i] = outcome.kind === "result" ? outcome.result : { name: entry.spec.name, mode: entry.spec.mode, input: entry.input, error: "Unexpected pause in parallel child." };
+        }
+      };
+      await Promise.all(Array.from({ length: concurrency }, () => worker()));
+      return { results };
+    }
+  });
+  tool._deps = deps;
+  tool._stateRef = {};
+  tool.__source = "smart-subagents";
+  return tool;
+}
+function createSubagentTools(deps) {
+  const tools = [];
+  if (deps.subagents.length > 0) tools.push(createDelegateTool(deps));
+  if (deps.policy.mode === "registry_and_adhoc") tools.push(createSpawnTool(deps));
+  tools.push(createParallelTool(deps));
+  return tools;
+}
+
 // src/smart/index.ts
 function createSmartAgent(opts) {
   const resolved = normalizeSmartAgentOptions(opts);
@@ -6415,6 +6941,42 @@ function createSmartAgent(opts) {
   const skills = opts.skills ?? [];
   const skillPolicy = opts.skillPolicy ?? DEFAULT_SKILL_POLICY;
   const skillsEnabled = skills.length > 0;
+  const subagentsProvided = opts.subagents !== void 0 || opts.subagentPolicy !== void 0;
+  const subagents = opts.subagents ?? [];
+  const subagentPolicy = opts.subagentPolicy ?? DEFAULT_SUBAGENT_POLICY;
+  const subagentsEnabled = subagentsProvided && subagentPolicy.mode !== "off" && (subagents.length > 0 || subagentPolicy.mode === "registry_and_adhoc");
+  const promptHooks = opts.promptHooks;
+  const buildChild = (cfg) => createSmartAgent({
+    name: cfg.name,
+    model: cfg.model,
+    tools: cfg.tools,
+    systemPrompt: cfg.systemPrompt,
+    outputSchema: cfg.outputSchema,
+    limits: cfg.limits,
+    runtimeProfile: resolved.runtimeProfile,
+    humanInTheLoop: opts.humanInTheLoop,
+    reasoning: opts.reasoning,
+    tokenCounter: opts.tokenCounter,
+    costEstimator: opts.costEstimator,
+    promptHooks,
+    // Sub-agents are single-level by design: a child never gets its own spawn
+    // tools, so it cannot delegate further. This keeps decomposition bounded and
+    // is why the depth guard mainly governs `asTool`-composed nesting (which seeds
+    // __delegationDepth externally) rather than sub-agent-of-sub-agent recursion.
+    subagents: [],
+    subagentPolicy: { ...subagentPolicy, mode: "off" }
+  });
+  const decorateToolDescriptions = (tools) => {
+    const overrides = promptHooks?.toolDescriptions;
+    if (!overrides) return tools;
+    return tools.map((tool) => {
+      const override = overrides[tool?.name];
+      if (override === void 0) return tool;
+      const next = typeof override === "function" ? override(tool.description || "") : override;
+      if (next === tool.description) return tool;
+      return { ...tool, description: next };
+    });
+  };
   const soManagerFactory = opts.outputSchema ? new StructuredOutputManager(opts.outputSchema, resolveStrategy(opts.model)) : void 0;
   const modelCapabilities = opts.outputSchema ? getModelCapabilities(opts.model) : void 0;
   const responseFinalizeTool = soManagerFactory && modelCapabilities?.structuredOutput !== "native" ? soManagerFactory.getResponseTool() : void 0;
@@ -6425,12 +6987,27 @@ function createSmartAgent(opts) {
     const coreBase = [...userTools, ...ctxTools];
     if (responseFinalizeTool) coreBase.push(responseFinalizeTool);
     if (askUserConfig) coreBase.push(createAskUserQuestionTool(ref, askUserConfig));
+    let subagentRegistryRef;
+    if (subagentsEnabled) {
+      subagentRegistryRef = createSubagentRegistryRef();
+      const deps = {
+        registryRef: subagentRegistryRef,
+        subagents,
+        policy: subagentPolicy,
+        buildChild
+        // NOTE: promptHooks.toolDescriptions overrides for the sub-agent tools are
+        // applied uniformly (and only) by decorateToolDescriptions below, so the
+        // function form of an override receives the real DEFAULT_* string. Baking
+        // them in here as well would double-apply and stringify the function.
+      };
+      coreBase.push(...createSubagentTools(deps));
+    }
     if (!skillsEnabled) {
-      const without = coreBase;
-      const withRec = [...without, recoveryTool];
-      return { stateRef: ref, toolsWithoutRecovery: without, toolsWithRecovery: withRec };
+      const without = decorateToolDescriptions(coreBase);
+      const withRec = decorateToolDescriptions([...coreBase, recoveryTool]);
+      return { stateRef: ref, toolsWithoutRecovery: without, toolsWithRecovery: withRec, subagentRegistryRef };
     }
-    const toolSet = { stateRef: ref, toolsWithoutRecovery: [], toolsWithRecovery: [] };
+    const toolSet = { stateRef: ref, toolsWithoutRecovery: [], toolsWithRecovery: [], subagentRegistryRef };
     const skillRegistryRef = createSkillRegistryRef();
     const skillMetaTools = createSkillTools({ registryRef: skillRegistryRef, skills, policy: skillPolicy });
     const baseWithMeta = [...coreBase, ...skillMetaTools];
@@ -6440,14 +7017,43 @@ function createSmartAgent(opts) {
         boundSkillTools: skillRegistryRef.boundSkillTools,
         recoveryTool
       });
-      toolSet.toolsWithoutRecovery = composed.toolsWithoutRecovery;
-      toolSet.toolsWithRecovery = composed.toolsWithRecovery;
+      toolSet.toolsWithoutRecovery = decorateToolDescriptions(composed.toolsWithoutRecovery);
+      toolSet.toolsWithRecovery = decorateToolDescriptions(composed.toolsWithRecovery);
     };
     skillRegistryRef.__onToolsChanged = rebuild;
     toolSet.skillRegistryRef = skillRegistryRef;
     rebuild();
     return toolSet;
   };
+  async function rehydrateSkillRegistry(ref, persisted) {
+    if (!persisted) return false;
+    const opened = Array.isArray(persisted.openedSkillKeys) ? persisted.openedSkillKeys : [];
+    const boundNames = new Set(Array.isArray(persisted.boundToolNames) ? persisted.boundToolNames : []);
+    if (opened.length === 0) return false;
+    let changed = false;
+    for (const key of opened) {
+      if (!ref.openedSkillKeys.includes(key)) ref.openedSkillKeys.push(key);
+      const skill = skills.find((s) => s.key === key);
+      if (!skill) continue;
+      let bound;
+      try {
+        bound = await skill.bindTools();
+      } catch {
+        continue;
+      }
+      const wanted = bound.filter((t) => boundNames.has(t.name));
+      const added = appendBoundTools(ref, wanted, skillPolicy);
+      if (added.length > 0) changed = true;
+    }
+    return changed;
+  }
+  function skillStateFromRegistry(ref) {
+    if (!ref || !Array.isArray(ref.openedSkillKeys) || ref.openedSkillKeys.length === 0) return void 0;
+    return {
+      openedSkillKeys: [...ref.openedSkillKeys],
+      boundToolNames: (ref.boundSkillTools || []).map((t) => t.name)
+    };
+  }
   const base = createAgent({ ...runtimeOpts, tools: factoryToolsWithoutRecovery });
   base.__runtime.runtimeProfile = resolved.runtimeProfile;
   base.__runtime.smart = resolved;
@@ -6498,12 +7104,19 @@ function createSmartAgent(opts) {
     };
   }
   function systemMessage2(extraBlock) {
-    const sys = buildSystemPrompt(
+    let sys = buildSystemPrompt(
       [opts.systemPrompt, runtimeHint, structuredOutputHint, extraBlock].filter(Boolean).join("\n"),
       planningEnabled,
       opts.name || "Agent",
       opts.todoListPrompt
     );
+    if (promptHooks?.transformSystemPrompt) {
+      try {
+        sys = promptHooks.transformSystemPrompt(sys, { agentName: opts.name || "Agent" });
+      } catch (err) {
+        console.warn("[agent-sdk] promptHooks.transformSystemPrompt error:", err);
+      }
+    }
     return { role: "system", content: sys };
   }
   function syncRuntimeTools(currentState, currentMessages, toolSet) {
@@ -6548,11 +7161,33 @@ function createSmartAgent(opts) {
       stateRef.todoList = input.plan?.steps;
       stateRef.planVersion = input.planVersion || input.plan?.version || 0;
       stateRef.adherenceScore = input.plan?.adherenceScore || 0;
+      if (skillsEnabled && toolSet.skillRegistryRef) {
+        const changed = await rehydrateSkillRegistry(toolSet.skillRegistryRef, input.ctx?.__skillState);
+        if (changed) toolSet.skillRegistryRef.__onToolsChanged?.();
+      }
       const syncPlanFromRef = (state2) => syncPlanStateWith(stateRef, state2);
       const availableSkills = skillsEnabled ? await resolveAvailableSkills(skills, { modelTier: skillPolicy.modelTier }) : [];
       const skillBlock = availableSkills.length > 0 ? buildSkillHeaderBlock(availableSkills) : void 0;
+      let subagentBlock;
+      if (subagentsEnabled) {
+        const availableSubagents = await resolveAvailableSubagents(subagents);
+        let block = buildSubagentCatalogBlock(availableSubagents, subagentPolicy, {
+          delegate: "delegate_to",
+          spawn: "spawn_subagent",
+          parallel: "spawn_subagents_parallel"
+        });
+        if (promptHooks?.subagentCatalog) {
+          try {
+            block = promptHooks.subagentCatalog(block, availableSubagents);
+          } catch (err) {
+            console.warn("[agent-sdk] promptHooks.subagentCatalog error:", err);
+          }
+        }
+        subagentBlock = block;
+      }
+      const disclosureBlock = [skillBlock, subagentBlock].filter(Boolean).join("\n\n") || void 0;
       const alreadyHasSystem = Array.isArray(input.messages) && input.messages[0]?.role === "system";
-      const seedMessages = alreadyHasSystem ? [...input.messages || []] : [systemMessage2(skillBlock), ...input.messages || []];
+      const seedMessages = alreadyHasSystem ? [...input.messages || []] : [systemMessage2(disclosureBlock), ...input.messages || []];
       let state = syncRuntimeTools(await syncMemory({ ...input, messages: seedMessages }), seedMessages, toolSet);
       let lastResult = null;
       let rawMessages = [...seedMessages];
@@ -6625,6 +7260,13 @@ function createSmartAgent(opts) {
       } else if (lastResult.state) {
         lastResult = { ...lastResult, state: { ...lastResult.state, memoryFacts: state.memoryFacts, plan: state.plan, planVersion: state.planVersion, messages: rawMessages } };
       }
+      if (skillsEnabled && lastResult.state) {
+        const persisted = skillStateFromRegistry(toolSet.skillRegistryRef);
+        if (persisted) {
+          const prevCtx = lastResult.state.ctx || {};
+          lastResult = { ...lastResult, state: { ...lastResult.state, ctx: { ...prevCtx, __skillState: persisted } } };
+        }
+      }
       return lastResult;
     },
     snapshot: base.snapshot,
@@ -6637,6 +7279,150 @@ function createSmartAgent(opts) {
   };
   return instance;
 }
+var FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+function parseSkillFrontmatter(md) {
+  const match = FRONTMATTER_RE.exec(md);
+  if (!match) return { metadata: {}, body: md.trim() };
+  return { metadata: parseFrontmatterBlock(match[1] ?? ""), body: md.slice(match[0].length).trim() };
+}
+var LIST_KEYS = /* @__PURE__ */ new Set([
+  "scripts",
+  "keywords",
+  "tags",
+  "allowed-tools",
+  "allowed_tools",
+  "compatible-models",
+  "compatible_models"
+]);
+function parseFrontmatterBlock(raw) {
+  const out = {};
+  let listKey = null;
+  let listAcc = [];
+  const flush = () => {
+    if (listKey) {
+      out[listKey] = listAcc;
+      listAcc = [];
+      listKey = null;
+    }
+  };
+  const splitList = (value) => value.split(",").map((v) => unquote(v.trim())).filter(Boolean);
+  for (const line of raw.split(/\r?\n/)) {
+    if (line.trim() === "") continue;
+    const item = /^\s*-\s+(.*)$/.exec(line);
+    if (item && listKey) {
+      listAcc.push(unquote(item[1].trim()));
+      continue;
+    }
+    flush();
+    const kv = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+    if (!kv) continue;
+    const [, key, rawValue] = kv;
+    const value = rawValue.trim();
+    if (value === "") {
+      listKey = key;
+    } else if (value.startsWith("[") && value.endsWith("]")) {
+      out[key] = splitList(value.slice(1, -1));
+    } else if (LIST_KEYS.has(key.toLowerCase())) {
+      out[key] = splitList(value);
+    } else {
+      out[key] = unquote(value);
+    }
+  }
+  flush();
+  return out;
+}
+function unquote(s) {
+  if (s.startsWith('"') && s.endsWith('"') || s.startsWith("'") && s.endsWith("'")) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+function asArray(v) {
+  if (v === void 0) return [];
+  return Array.isArray(v) ? v : [v];
+}
+function sanitize(s) {
+  return s.replace(/[^A-Za-z0-9_]+/g, "_").replace(/^_+|_+$/g, "");
+}
+function scriptToolName(skillName, scriptFile) {
+  const base = scriptFile.replace(/\.[^.]+$/, "");
+  return `${sanitize(skillName)}__${sanitize(base)}`;
+}
+var join = (...parts) => parts.join("/").replace(/\/{2,}/g, "/");
+function buildScriptTools(skillName, skillDir, scripts, execution) {
+  const tools = scripts.map(
+    (file) => createTool({
+      name: scriptToolName(skillName, file),
+      description: `Run the bundled "${file}" script from the "${skillName}" skill.`,
+      schema: z.object({
+        args: z.record(z.any()).optional().describe("Arguments passed to the script.")
+      }),
+      needsApproval: true,
+      approvalPrompt: `Run script ${file} from skill ${skillName}?`,
+      func: (input) => execution.executeScript(join(skillDir, "scripts", file), input?.args ?? {})
+    })
+  );
+  const headers = tools.map((t) => ({ name: t.name, description: t.description }));
+  return { headers, tools };
+}
+async function loadOneSkill(fs2, skillDir, fallbackName, execution, minModelTier) {
+  let md;
+  try {
+    md = await fs2.readFile(join(skillDir, "SKILL.md"));
+  } catch {
+    return null;
+  }
+  const { metadata, body } = parseSkillFrontmatter(md);
+  const name = metadata.name ?? fallbackName;
+  const description = metadata.description ?? "";
+  const tier = metadata["min-model-tier"] ?? minModelTier;
+  let scripts = asArray(metadata.scripts);
+  if (scripts.length === 0) {
+    try {
+      scripts = await fs2.listDir(join(skillDir, "scripts"));
+    } catch {
+      scripts = [];
+    }
+  }
+  const built = execution && scripts.length > 0 ? buildScriptTools(name, skillDir, scripts, execution) : { headers: [], tools: [] };
+  const skill = {
+    key: `skillmd:${name}`,
+    title: name,
+    header: description,
+    prompt: body,
+    needsSandbox: scripts.length > 0,
+    listToolIndex: () => built.headers,
+    bindTools: (names) => names ? built.tools.filter((t) => names.includes(t.name)) : built.tools
+  };
+  if (tier) skill.minModelTier = tier;
+  return skill;
+}
+async function loadSkillsFromDisk(opts) {
+  const skills = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const root of opts.roots) {
+    let entries;
+    try {
+      entries = await opts.fs.listDir(root);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const skill = await loadOneSkill(
+        opts.fs,
+        join(root, entry),
+        entry,
+        opts.execution,
+        opts.minModelTier
+      );
+      if (skill && !seen.has(skill.key)) {
+        seen.add(skill.key);
+        skills.push(skill);
+      }
+    }
+  }
+  return skills;
+}
 
 // src/smart/eval.ts
 function normalizeProfileTarget(target) {
@@ -9333,6 +10119,6 @@ function createProvider(config) {
   }
 }
 
-export { AnthropicProvider, AzureProvider, BaseProvider, BedrockProvider, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, GuardrailPhase, InMemoryMemoryStore, NativeJsonSchemaStrategy, OpenAICompatibleProvider, OpenAIProvider, ProviderError, SMALL_TIER_SKILL_POLICY, StructuredOutputManager, ToolBasedStrategy, VertexProvider, agentVerdictRule, appendBoundTools, buildSkillHeaderBlock, buildSystemPrompt, canOpenSkill, captureSnapshot, codePresenceRule, cognipeerSink, composeToolSets, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextSummarizeNode, createContextTools, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createProvider, createRegexGuardrail, createResolverNode, createSkillRegistryRef, createSkillTools, createSmartAgent, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, emptyUsage, evaluateGuardrails, fileSink, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, normalizeSmartAgentOptions, otlpSink, readMemoryFacts, regexRule, resolveAvailableSkills, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, setTokenCounter, startStreamingSession, traceSessionToOtlp, validateReasoningConfig, withTools, writeSummaryFactsToMemory };
+export { AnthropicProvider, AzureProvider, BaseProvider, BedrockProvider, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, DEFAULT_SUBAGENT_POLICY, DEFAULT_SUBAGENT_TOOL_NAMES, GuardrailPhase, InMemoryMemoryStore, NativeJsonSchemaStrategy, OpenAICompatibleProvider, OpenAIProvider, ProviderError, SMALL_TIER_SKILL_POLICY, StructuredOutputManager, ToolBasedStrategy, VertexProvider, agentVerdictRule, appendBoundTools, buildSkillHeaderBlock, buildSubagentCatalogBlock, buildSystemPrompt, canOpenSkill, canSpawn, captureSnapshot, codePresenceRule, cognipeerSink, composeToolSets, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextSummarizeNode, createContextTools, createDelegateTool, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createParallelTool, createProvider, createRegexGuardrail, createResolverNode, createSkillRegistryRef, createSkillTools, createSmartAgent, createSpawnTool, createSubagentRegistryRef, createSubagentTools, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, emptyUsage, evaluateGuardrails, fileSink, findSubagent, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, loadSkillsFromDisk, normalizeSmartAgentOptions, otlpSink, parseSkillFrontmatter, readMemoryFacts, regexRule, resolveAvailableSkills, resolveAvailableSubagents, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveSubagentTools, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, seedChildMessages, setTokenCounter, startStreamingSession, traceSessionToOtlp, validateReasoningConfig, withTools, withinDepth, writeSummaryFactsToMemory };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map