@librechat/agents 3.1.66 → 3.1.67-dev.0

package/dist/types/index.d.ts

@@ -7,7 +7,14 @@ export * from './graphs';
 export * from './summarization';
 export * from './tools/Calculator';
 export * from './tools/CodeExecutor';
+export * from './tools/BashExecutor';
 export * from './tools/ProgrammaticToolCalling';
+export * from './tools/BashProgrammaticToolCalling';
+export * from './tools/SkillTool';
+export * from './tools/SubagentTool';
+export * from './tools/subagent';
+export * from './tools/ReadFile';
+export * from './tools/skillCatalog';
 export * from './tools/ToolSearch';
 export * from './tools/ToolNode';
 export * from './tools/schema';
@@ -15,6 +22,7 @@ export * from './tools/handlers';
 export * from './tools/search';
 export * from './common';
 export * from './utils';
+export * from './hooks';
 export type * from './types';
 export { CustomOpenAIClient } from './llm/openai';
 export { ChatOpenRouter } from './llm/openrouter';

package/dist/types/messages/format.d.ts

@@ -104,9 +104,10 @@ export declare const labelContentByAgent: (contentParts: MessageContentComplex[]
  * @param payload - The array of messages to format.
  * @param indexTokenCountMap - Optional map of message indices to token counts.
  * @param tools - Optional set of tool names that are allowed in the request.
+ * @param skills - Optional map of skill name to body for reconstructing skill HumanMessages.
  * @returns - Object containing formatted messages and updated indexTokenCountMap if provided.
  */
-export declare const formatAgentMessages: (payload: TPayload, indexTokenCountMap?: Record<number, number | undefined>, tools?: Set<string>) => {
+export declare const formatAgentMessages: (payload: TPayload, indexTokenCountMap?: Record<number, number | undefined>, tools?: Set<string>, skills?: Map<string, string>) => {
     messages: Array<HumanMessage | AIMessage | SystemMessage | ToolMessage>;
     indexTokenCountMap?: Record<number, number>;
     /** Cross-run summary extracted from the payload. Should be forwarded to the

package/dist/types/run.d.ts

@@ -9,6 +9,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     id: string;
     private tokenCounter?;
     private handlerRegistry?;
+    private hookRegistry?;
     private indexTokenCountMap?;
     calibrationRatio: number;
     graphRunnable?: t.CompiledStateWorkflow;

package/dist/types/summarization/node.d.ts

@@ -1,6 +1,7 @@
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseMessage } from '@langchain/core/messages';
 import type { AgentContext } from '@/agents/AgentContext';
+import type { HookRegistry } from '@/hooks';
 import type * as t from '@/types';
 /** Structured checkpoint prompt for fresh summarization (no prior summary). */
 export declare const DEFAULT_SUMMARIZATION_PROMPT = "Hold on, before you continue I need you to write me a checkpoint of everything so far. Your context window is filling up and this checkpoint replaces the messages above, so capture everything you need to pick right back up.\n\nDon't second-guess or fact-check anything you did, your tool results reflect exactly what happened. If a tool result appears truncated, that's just a display artifact from context management: the tool executed fully. Just record what you did and what you observed. Only the checkpoint, don't respond to me or continue the conversation.\n\n## Checkpoint\n\n## Goal\nWhat I asked you to do and any sub-goals you identified.\n\n## Constraints & Preferences\nAny rules, preferences, or configuration I established.\n\n## Progress\n### Done\n- What you completed and the outcomes\n\n### In Progress\n- What you're currently working on\n\n## Key Decisions\nDecisions you made and why.\n\n## Next Steps\nConcrete task actions remaining, in priority order.\n\n## Critical Context\nExact identifiers, names, error messages, URLs, and details you need to preserve verbatim.\n\nRules:\n- Record what you did and observed, don't judge or re-evaluate it\n- For each tool call: the tool name, key inputs, and the outcome\n- Preserve exact identifiers, names, errors, and references verbatim\n- Short declarative sentences\n- Skip empty sections";
@@ -14,6 +15,7 @@ interface CreateSummarizeNodeParams {
         config?: RunnableConfig;
         runId?: string;
         isMultiAgent: boolean;
+        hookRegistry?: HookRegistry;
         dispatchRunStep: (runStep: t.RunStep, config?: RunnableConfig) => Promise<void>;
         dispatchRunStepCompleted: (stepId: string, result: t.StepCompleted, config?: RunnableConfig) => Promise<void>;
     };

package/dist/types/tools/BashExecutor.d.ts

@@ -0,0 +1,45 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+import { Constants } from '@/common';
+export declare const BashExecutionToolSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly command: {
+            readonly type: "string";
+            readonly description: "The bash command or script to execute.\n- The environment is stateless; variables and state don't persist between executions.\n- Generated files from previous executions are automatically available in \"/mnt/data/\".\n- Files from previous executions are automatically available and can be modified in place.\n- Input code **IS ALREADY** displayed to the user, so **DO NOT** repeat it in your response unless asked.\n- Output code **IS NOT** displayed to the user, so **DO** write all desired output explicitly.\n- IMPORTANT: You MUST explicitly print/output ALL results you want the user to see.\n- Use `echo`, `printf`, or `cat` for all outputs.";
+        };
+        readonly args: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Additional arguments to execute the command with. This should only be used if the input command requires additional arguments to run.";
+        };
+    };
+    readonly required: readonly ["command"];
+};
+export declare const BashExecutionToolDescription: string;
+export declare const BashExecutionToolName = Constants.BASH_TOOL;
+export declare const BashExecutionToolDefinition: {
+    readonly name: Constants.BASH_TOOL;
+    readonly description: string;
+    readonly schema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly command: {
+                readonly type: "string";
+                readonly description: "The bash command or script to execute.\n- The environment is stateless; variables and state don't persist between executions.\n- Generated files from previous executions are automatically available in \"/mnt/data/\".\n- Files from previous executions are automatically available and can be modified in place.\n- Input code **IS ALREADY** displayed to the user, so **DO NOT** repeat it in your response unless asked.\n- Output code **IS NOT** displayed to the user, so **DO** write all desired output explicitly.\n- IMPORTANT: You MUST explicitly print/output ALL results you want the user to see.\n- Use `echo`, `printf`, or `cat` for all outputs.";
+            };
+            readonly args: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Additional arguments to execute the command with. This should only be used if the input command requires additional arguments to run.";
+            };
+        };
+        readonly required: readonly ["command"];
+    };
+};
+declare function createBashExecutionTool(params?: t.BashExecutionToolParams): DynamicStructuredTool;
+export { createBashExecutionTool };

package/dist/types/tools/BashProgrammaticToolCalling.d.ts

@@ -0,0 +1,72 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+import { Constants } from '@/common';
+export declare const BashProgrammaticToolCallingSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly code: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "Bash code that calls tools programmatically. Tools are available as bash functions.\n\nCRITICAL - STATELESS EXECUTION:\nEach call is a fresh bash shell. Variables and state do NOT persist between calls.\nYou MUST complete your entire workflow in ONE code block.\nDO NOT split work across multiple calls expecting to reuse variables.\n\nEach tool function accepts a JSON string as its argument.\nExample: tool_name '{\"key\": \"value\"}'\n\nExample (Complete workflow in one call):\n  # Query data and process\n  data=$(query_database '{\"sql\": \"SELECT * FROM users\"}')\n  echo \"$data\" | jq '.[] | .name'\n\nExample (Parallel calls):\n  web_search '{\"query\": \"SF weather\"}' > /tmp/sf.txt &\n  web_search '{\"query\": \"NY weather\"}' > /tmp/ny.txt &\n  wait\n  echo \"SF: $(cat /tmp/sf.txt)\"\n  echo \"NY: $(cat /tmp/ny.txt)\"\n\nRules:\n- EVERYTHING in one call—no state persists between executions\n- Tools are pre-defined as bash functions—DO NOT redefine them\n- Each tool function accepts a JSON string argument\n- Only echo/printf output returns to the model\n- Generated files are automatically available in /mnt/data/ for subsequent executions";
+        };
+        readonly timeout: {
+            readonly type: "integer";
+            readonly minimum: 1000;
+            readonly maximum: 300000;
+            readonly default: 60000;
+            readonly description: "Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes.";
+        };
+    };
+    readonly required: readonly ["code"];
+};
+export declare const BashProgrammaticToolCallingName = Constants.BASH_PROGRAMMATIC_TOOL_CALLING;
+export declare const BashProgrammaticToolCallingDescription: string;
+export declare const BashProgrammaticToolCallingDefinition: {
+    readonly name: Constants.BASH_PROGRAMMATIC_TOOL_CALLING;
+    readonly description: string;
+    readonly schema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly code: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "Bash code that calls tools programmatically. Tools are available as bash functions.\n\nCRITICAL - STATELESS EXECUTION:\nEach call is a fresh bash shell. Variables and state do NOT persist between calls.\nYou MUST complete your entire workflow in ONE code block.\nDO NOT split work across multiple calls expecting to reuse variables.\n\nEach tool function accepts a JSON string as its argument.\nExample: tool_name '{\"key\": \"value\"}'\n\nExample (Complete workflow in one call):\n  # Query data and process\n  data=$(query_database '{\"sql\": \"SELECT * FROM users\"}')\n  echo \"$data\" | jq '.[] | .name'\n\nExample (Parallel calls):\n  web_search '{\"query\": \"SF weather\"}' > /tmp/sf.txt &\n  web_search '{\"query\": \"NY weather\"}' > /tmp/ny.txt &\n  wait\n  echo \"SF: $(cat /tmp/sf.txt)\"\n  echo \"NY: $(cat /tmp/ny.txt)\"\n\nRules:\n- EVERYTHING in one call—no state persists between executions\n- Tools are pre-defined as bash functions—DO NOT redefine them\n- Each tool function accepts a JSON string argument\n- Only echo/printf output returns to the model\n- Generated files are automatically available in /mnt/data/ for subsequent executions";
+            };
+            readonly timeout: {
+                readonly type: "integer";
+                readonly minimum: 1000;
+                readonly maximum: 300000;
+                readonly default: 60000;
+                readonly description: "Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes.";
+            };
+        };
+        readonly required: readonly ["code"];
+    };
+};
+/**
+ * Normalizes a tool name to a valid bash function identifier.
+ * 1. Replace hyphens, spaces, dots with underscores
+ * 2. Remove any other invalid characters
+ * 3. Prefix with underscore if starts with number
+ * 4. Append `_tool` if it's a bash reserved word
+ */
+export declare function normalizeToBashIdentifier(name: string): string;
+/**
+ * Extracts tool names that are actually called in the bash code.
+ * Bash functions are invoked as commands (no parentheses), so we match
+ * the normalized name as a word boundary.
+ */
+export declare function extractUsedBashToolNames(code: string, toolNameMap: Map<string, string>): Set<string>;
+/**
+ * Filters tool definitions to only include tools actually used in the bash code.
+ */
+export declare function filterBashToolsByUsage(toolDefs: t.LCTool[], code: string, debug?: boolean): t.LCTool[];
+/**
+ * Creates a Bash Programmatic Tool Calling tool for multi-tool orchestration.
+ *
+ * This tool enables AI agents to write bash scripts that orchestrate multiple
+ * tool calls programmatically via the remote Code API, reducing LLM round-trips.
+ *
+ * The tool map must be provided at runtime via config.toolCall (injected by ToolNode).
+ */
+export declare function createBashProgrammaticToolCallingTool(initParams?: t.BashProgrammaticToolCallingParams): DynamicStructuredTool;

package/dist/types/tools/ReadFile.d.ts

@@ -0,0 +1,28 @@
+import { Constants } from '@/common';
+export declare const ReadFileToolName = Constants.READ_FILE;
+export declare const ReadFileToolDescription = "Read the contents of a file. Returns text content with line numbers for easy reference.\n\nFor skill files, use the path format: {skillName}/{filePath} (e.g. \"pdf-analyzer/src/utils.py\", \"code-review/SKILL.md\").\n\nBEHAVIOR:\n- Text files: returned with numbered lines.\n- Images (png, jpeg, gif, webp): returned as visual content the model can see.\n- PDFs: returned as document content.\n- Other binary files: metadata returned with a note to use bash for processing.\n- Large files (>256KB text, >10MB binary): metadata only.\n- SKILL.md: returns the skill's instructions directly.\n\nCONSTRAINTS:\n- Only files from invoked skills or code execution output are accessible.\n- Do not guess file paths. Use paths from the skill documentation or tool output.";
+export declare const ReadFileToolSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly file_path: {
+            readonly type: "string";
+            readonly description: "Path to the file. For skill files: \"{skillName}/{path}\" (e.g. \"pdf-analyzer/src/utils.py\"). For code execution output: the path as returned by the execution tool.";
+        };
+    };
+    readonly required: readonly ["file_path"];
+};
+export declare const ReadFileToolDefinition: {
+    readonly name: Constants.READ_FILE;
+    readonly description: "Read the contents of a file. Returns text content with line numbers for easy reference.\n\nFor skill files, use the path format: {skillName}/{filePath} (e.g. \"pdf-analyzer/src/utils.py\", \"code-review/SKILL.md\").\n\nBEHAVIOR:\n- Text files: returned with numbered lines.\n- Images (png, jpeg, gif, webp): returned as visual content the model can see.\n- PDFs: returned as document content.\n- Other binary files: metadata returned with a note to use bash for processing.\n- Large files (>256KB text, >10MB binary): metadata only.\n- SKILL.md: returns the skill's instructions directly.\n\nCONSTRAINTS:\n- Only files from invoked skills or code execution output are accessible.\n- Do not guess file paths. Use paths from the skill documentation or tool output.";
+    readonly parameters: {
+        readonly type: "object";
+        readonly properties: {
+            readonly file_path: {
+                readonly type: "string";
+                readonly description: "Path to the file. For skill files: \"{skillName}/{path}\" (e.g. \"pdf-analyzer/src/utils.py\"). For code execution output: the path as returned by the execution tool.";
+            };
+        };
+        readonly required: readonly ["file_path"];
+    };
+    readonly responseFormat: "content_and_artifact";
+};

package/dist/types/tools/SkillTool.d.ts

@@ -0,0 +1,40 @@
+import { Constants } from '@/common';
+export declare const SkillToolName = Constants.SKILL_TOOL;
+export declare const SkillToolDescription = "Invoke a skill from the user's library. Skills provide domain-specific instructions loaded into the conversation context, and may also provide files accessible via available tools depending on the runtime environment.\n\nWHEN TO USE:\n- The user's request matches a skill listed in the \"Available Skills\" section of the system prompt.\n- You MUST invoke the matching skill BEFORE attempting the task yourself.\n\nWHAT HAPPENS:\n- The skill's full instructions are loaded into the conversation as context.\n- Files bundled with the skill may become accessible via available tools.\n- Follow the skill's instructions to complete the task.\n\nCONSTRAINTS:\n- Do not invoke a skill that is already active in this conversation.\n- Skill names come from the catalog only. Do not guess names.";
+/**
+ * JSON Schema for the SkillTool parameters.
+ * Single source of truth used by both SkillToolDefinition (LCTool registry)
+ * and createSkillTool() (DynamicStructuredTool instance).
+ */
+export declare const SkillToolSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly skillName: {
+            readonly type: "string";
+            readonly description: "The kebab-case identifier of the skill to invoke (e.g. \"financial-analyzer\", \"meeting-notes\"). Must match a name from the \"Available Skills\" section.";
+        };
+        readonly args: {
+            readonly type: "string";
+            readonly description: "Optional freeform arguments string passed to the skill.";
+        };
+    };
+    readonly required: readonly ["skillName"];
+};
+export declare const SkillToolDefinition: {
+    readonly name: Constants.SKILL_TOOL;
+    readonly description: "Invoke a skill from the user's library. Skills provide domain-specific instructions loaded into the conversation context, and may also provide files accessible via available tools depending on the runtime environment.\n\nWHEN TO USE:\n- The user's request matches a skill listed in the \"Available Skills\" section of the system prompt.\n- You MUST invoke the matching skill BEFORE attempting the task yourself.\n\nWHAT HAPPENS:\n- The skill's full instructions are loaded into the conversation as context.\n- Files bundled with the skill may become accessible via available tools.\n- Follow the skill's instructions to complete the task.\n\nCONSTRAINTS:\n- Do not invoke a skill that is already active in this conversation.\n- Skill names come from the catalog only. Do not guess names.";
+    readonly parameters: {
+        readonly type: "object";
+        readonly properties: {
+            readonly skillName: {
+                readonly type: "string";
+                readonly description: "The kebab-case identifier of the skill to invoke (e.g. \"financial-analyzer\", \"meeting-notes\"). Must match a name from the \"Available Skills\" section.";
+            };
+            readonly args: {
+                readonly type: "string";
+                readonly description: "Optional freeform arguments string passed to the skill.";
+            };
+        };
+        readonly required: readonly ["skillName"];
+    };
+};

package/dist/types/tools/SubagentTool.d.ts

@@ -0,0 +1,36 @@
+import { Constants } from '@/common';
+import type { SubagentConfig } from '@/types';
+import type { JsonSchemaType, LCTool } from '@/types/tools';
+export declare const SubagentToolName = Constants.SUBAGENT;
+export declare const SubagentToolDescription = "Delegate a task to a specialized subagent that runs in an isolated context window. The subagent executes independently and returns only its final text result \u2014 all intermediate tool calls, reasoning, and context stay isolated.\n\nWHEN TO USE:\n- The task is self-contained and can be described in a single prompt.\n- You want to offload verbose or exploratory work without bloating your own context.\n- A specialized subagent is available for the task domain.\n\nWHAT HAPPENS:\n- A fresh agent is created with the task description as its only input.\n- The subagent runs to completion using its own tools and context.\n- Only the final text response is returned to you.\n\nCONSTRAINTS:\n- subagent_type must match one of the available types listed below.\n- The subagent cannot see your conversation history.";
+export declare const SubagentToolSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly description: {
+            readonly type: "string";
+            readonly description: "Complete task description for the subagent. This is the ONLY information it receives — include all necessary context, requirements, and constraints.";
+        };
+        readonly subagent_type: {
+            readonly type: "string";
+            readonly description: "Which subagent type to delegate to. Must be one of the available types.";
+        };
+    };
+    readonly required: string[];
+};
+export declare const SubagentToolDefinition: LCTool;
+/**
+ * Build the name, schema, and description params for `tool()` from available configs.
+ * Used by `Graph.createAgentNode()` when constructing the runtime tool instance.
+ * Extends `SubagentToolSchema` by populating `subagent_type.enum` dynamically.
+ */
+export declare function buildSubagentToolParams(configs: SubagentConfig[]): {
+    name: string;
+    schema: JsonSchemaType;
+    description: string;
+};
+/**
+ * Create a SubagentTool LCTool definition with dynamic enum and description
+ * populated from the available subagent configs.
+ * Used for the tool registry in event-driven mode.
+ */
+export declare function createSubagentToolDefinition(configs: SubagentConfig[]): LCTool;

package/dist/types/tools/ToolNode.d.ts

@@ -28,7 +28,9 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private directToolNames?;
     /** Maximum characters allowed in a single tool result before truncation. */
     private maxToolResultChars;
-    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, maxContextTokens, maxToolResultChars, }: t.ToolNodeConstructorParams);
+    /** Hook registry for PreToolUse/PostToolUse lifecycle hooks */
+    private hookRegistry?;
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, maxContextTokens, maxToolResultChars, hookRegistry, }: t.ToolNodeConstructorParams);
     /**
      * Returns cached programmatic tools, computing once on first access.
      * Single iteration builds both toolMap and toolDefs simultaneously.
@@ -66,11 +68,31 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     /**
      * Dispatches tool calls to the host via ON_TOOL_EXECUTE event and returns raw ToolMessages.
      * Core logic for event-driven execution, separated from output shaping.
+     *
+     * Hook lifecycle (when `hookRegistry` is set):
+     * 1. **PreToolUse** fires per call in parallel before dispatch. Denied
+     *    calls produce error ToolMessages and fire **PermissionDenied**;
+     *    surviving calls proceed with optional `updatedInput`.
+     * 2. Surviving calls are dispatched to the host via `ON_TOOL_EXECUTE`.
+     * 3. **PostToolUse** / **PostToolUseFailure** fire per result. Post hooks
+     *    can replace tool output via `updatedOutput`.
+     * 4. Injected messages from results are collected and returned alongside
+     *    ToolMessages (appended AFTER to respect provider ordering).
      */
     private dispatchToolEvents;
+    private dispatchStepCompleted;
+    /**
+     * Converts InjectedMessage instances to LangChain HumanMessage objects.
+     * Both 'user' and 'system' roles become HumanMessage to avoid provider
+     * rejections (Anthropic/Google reject non-leading SystemMessages).
+     * The original role is preserved in additional_kwargs for downstream consumers.
+     */
+    private convertInjectedMessages;
     /**
      * Execute all tool calls via ON_TOOL_EXECUTE event dispatch.
-     * Used in event-driven mode where the host handles actual tool execution.
+     * Injected messages are placed AFTER ToolMessages to respect provider
+     * message ordering (AIMessage tool_calls must be immediately followed
+     * by their ToolMessage results).
      */
     private executeViaEvent;
     protected run(input: any, config: RunnableConfig): Promise<T>;

package/dist/types/tools/skillCatalog.d.ts

@@ -0,0 +1,19 @@
+import type { SkillCatalogEntry } from '@/types';
+export type SkillCatalogOptions = {
+    /** Total context window in tokens. Default: 200_000 */
+    contextWindowTokens?: number;
+    /** Fraction of context budget for catalog. Default: 0.01 (1%) */
+    budgetPercent?: number;
+    /** Max chars per entry description. Default: 250 */
+    maxEntryChars?: number;
+    /** Descriptions below this length trigger names-only fallback. Default: 20 */
+    minDescLength?: number;
+    /** Approximate chars per token for budget calculation. Default: 4 */
+    charsPerToken?: number;
+};
+/**
+ * Formats a skill catalog for injection into agent context.
+ * Uses a truncation ladder: full descriptions, proportional truncation, names-only.
+ * Returns empty string for empty input.
+ */
+export declare function formatSkillCatalog(skills: SkillCatalogEntry[], opts?: SkillCatalogOptions): string;

package/dist/types/tools/subagent/SubagentExecutor.d.ts

@@ -0,0 +1,83 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type { AgentInputs, StandardGraphInput, ResolvedSubagentConfig, SubagentConfig, TokenCounter } from '@/types';
+import type { HookRegistry } from '@/hooks';
+import type { AgentContext } from '@/agents/AgentContext';
+import type { StandardGraph } from '@/graphs/Graph';
+export type SubagentExecuteParams = {
+    description: string;
+    subagentType: string;
+    threadId?: string;
+};
+export type SubagentExecuteResult = {
+    content: string;
+    messages: BaseMessage[];
+};
+/**
+ * Factory that constructs a child graph for subagent execution. Injected
+ * rather than imported so that `SubagentExecutor` does not have a runtime
+ * dependency on `StandardGraph` — this avoids a circular dependency between
+ * `src/graphs/Graph.ts` and `src/tools/subagent/` that would otherwise break
+ * Rollup's chunking under `preserveModules`.
+ */
+export type ChildGraphFactory = (input: StandardGraphInput) => StandardGraph;
+export type SubagentExecutorOptions = {
+    configs: Map<string, ResolvedSubagentConfig>;
+    parentSignal?: AbortSignal;
+    hookRegistry?: HookRegistry;
+    parentRunId: string;
+    parentAgentId?: string;
+    tokenCounter?: TokenCounter;
+    /** Remaining nesting budget. 0 or negative blocks execution. */
+    maxDepth?: number;
+    /**
+     * Factory for constructing the isolated child graph. Callers pass
+     * `(input) => new StandardGraph(input)` — injected to break a circular
+     * module dependency.
+     */
+    createChildGraph: ChildGraphFactory;
+};
+export declare class SubagentExecutor {
+    private readonly configs;
+    private readonly parentSignal?;
+    private readonly hookRegistry?;
+    private readonly parentRunId;
+    private readonly parentAgentId?;
+    private readonly tokenCounter?;
+    private readonly maxDepth;
+    private readonly createChildGraph;
+    constructor(options: SubagentExecutorOptions);
+    execute(params: SubagentExecuteParams): Promise<SubagentExecuteResult>;
+}
+/**
+ * Walk messages from last to first, returning the text content of the most
+ * recent AIMessage that has any. Non-text blocks (tool_use, thinking,
+ * redacted_thinking, tool_result) are stripped. If the last AIMessage is
+ * pure tool_use (e.g. the subagent hit `maxTurns` mid-tool-call), the walk
+ * continues to earlier AIMessages so partial progress is salvaged — this
+ * matches Claude Code's behavior in `agentToolUtils.finalizeAgentTool`.
+ * Returns "Task completed" only when no AIMessage in the history contains
+ * any text.
+ */
+export declare function filterSubagentResult(messages: BaseMessage[]): string;
+/**
+ * Resolve self-spawn configs by filling in agentInputs from the parent context.
+ * Returns configs with agentInputs guaranteed present. Throws on duplicate
+ * `type` values to prevent silent config shadowing.
+ */
+export declare function resolveSubagentConfigs(configs: SubagentConfig[], parentContext: AgentContext): ResolvedSubagentConfig[];
+/**
+ * Build child AgentInputs from a resolved config, stripping nesting and
+ * event-driven fields. When `allowNested: true`, the child's
+ * `maxSubagentDepth` is decremented so that depth is consumed as the call
+ * chain deepens across graph boundaries — the parent's executor-level check
+ * alone cannot see into the child graph's separate executor.
+ *
+ * @remarks Advanced utility: exported primarily for testing and by
+ * {@link SubagentExecutor}. Host applications configuring subagents should
+ * not need to call this directly — it is invoked internally when a subagent
+ * tool is dispatched. The depth-countdown contract (parent's `maxDepth` in,
+ * child's decremented `maxSubagentDepth` on the returned inputs) is the
+ * mechanism that bounds nesting across graph boundaries; callers must
+ * respect it.
+ */
+export declare function buildChildInputs(config: ResolvedSubagentConfig, childAgentId: string, parentMaxDepth: number): AgentInputs;

package/dist/types/tools/subagent/index.d.ts

@@ -0,0 +1,2 @@
+export { SubagentExecutor, filterSubagentResult, resolveSubagentConfigs, buildChildInputs, } from './SubagentExecutor';
+export type { SubagentExecuteParams, SubagentExecuteResult, SubagentExecutorOptions, ChildGraphFactory, } from './SubagentExecutor';

package/dist/types/types/graph.d.ts

@@ -248,6 +248,27 @@ export type GraphEdge = {
 export type MultiAgentGraphInput = StandardGraphInput & {
     edges: GraphEdge[];
 };
+/** Configuration for a subagent type that can be spawned by a parent agent. */
+export type SubagentConfig = {
+    /** Identifier used in the tool's `subagent_type` enum (e.g. 'researcher', 'coder'). */
+    type: string;
+    /** Human-readable display name. */
+    name: string;
+    /** What this subagent specializes in — shown to the LLM. */
+    description: string;
+    /** Full agent config for the child graph. Omit when `self` is true. */
+    agentInputs?: AgentInputs;
+    /** When true, reuse the parent's AgentInputs (context isolation without separate config). */
+    self?: boolean;
+    /** Max AGENT→TOOLS cycles before forced stop (default: 25). */
+    maxTurns?: number;
+    /** Allow this subagent to spawn its own subagents (default: false). */
+    allowNested?: boolean;
+};
+/** SubagentConfig with agentInputs guaranteed present (self-spawn resolved). */
+export type ResolvedSubagentConfig = SubagentConfig & {
+    agentInputs: AgentInputs;
+};
 export interface AgentInputs {
     agentId: string;
     /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */
@@ -294,6 +315,10 @@ export interface AgentInputs {
     maxToolResultChars?: number;
     /** Pre-computed tool schema token count (from cache). Skips recalculation when provided. */
     toolSchemaTokens?: number;
+    /** Subagent configurations for hierarchical delegation. Each defines a child agent type. */
+    subagentConfigs?: SubagentConfig[];
+    /** Maximum subagent nesting depth. Default 1 means top-level agents can spawn subagents but subagents cannot nest further. */
+    maxSubagentDepth?: number;
 }
 export interface ContextPruningConfig {
     enabled?: boolean;

package/dist/types/types/index.d.ts

@@ -1,6 +1,7 @@
 export * from './graph';
 export * from './llm';
 export * from './run';
+export * from './skill';
 export * from './stream';
 export * from './tools';
 export * from './summarize';

package/dist/types/types/llm.d.ts

@@ -28,7 +28,18 @@ export type AzureClientOptions = Partial<OpenAIChatInput> & Partial<AzureOpenAII
 } & BaseChatModelParams & {
     configuration?: OAIClientOptions;
 };
-export type ThinkingConfig = AnthropicInput['thinking'];
+/**
+ * Controls whether Claude's reasoning content is returned in adaptive
+ * thinking responses. Added for Claude Opus 4.7, which omits thinking by
+ * default unless the caller opts in with `'summarized'`.
+ * @see https://platform.claude.com/docs/en/about-claude/models/whats-new-claude-4-7#thinking-content-omitted-by-default
+ */
+export type ThinkingDisplay = 'summarized' | 'omitted';
+export type ThinkingConfigAdaptive = {
+    type: 'adaptive';
+    display?: ThinkingDisplay;
+};
+export type ThinkingConfig = NonNullable<AnthropicInput['thinking']> | ThinkingConfigAdaptive;
 export type ChatOpenAIToolType = BindToolsInput | OpenAIClient.ChatCompletionTool;
 export type CommonToolType = StructuredTool | ChatOpenAIToolType;
 export type AnthropicReasoning = {
@@ -41,7 +52,8 @@ export type GoogleThinkingConfig = {
     thinkingLevel?: string;
 };
 export type OpenAIClientOptions = ChatOpenAIFields;
-export type AnthropicClientOptions = AnthropicInput & {
+export type AnthropicClientOptions = Omit<AnthropicInput, 'thinking'> & {
+    thinking?: ThinkingConfig;
     promptCache?: boolean;
 };
 export type MistralAIClientOptions = ChatMistralAIInput;

package/dist/types/types/run.d.ts

@@ -7,6 +7,8 @@ import type * as s from '@/types/stream';
 import type * as e from '@/common/enum';
 import type * as g from '@/types/graph';
 import type * as l from '@/types/llm';
+import type { ToolSessionMap } from '@/types/tools';
+import type { HookRegistry } from '@/hooks';
 export type ZodObjectAny = z.ZodObject<any, any, any, any>;
 export type BaseGraphConfig = {
     llmConfig: l.LLMConfig;
@@ -100,6 +102,18 @@ export type RunConfig = {
     runId: string;
     graphConfig: LegacyGraphConfig | StandardGraphConfig | MultiAgentGraphConfig;
     customHandlers?: Record<string, g.EventHandler>;
+    /**
+     * Pre-constructed hook registry for this run. Hooks fire at lifecycle
+     * points in `processStream` (RunStart, UserPromptSubmit, Stop,
+     * StopFailure) and around tool calls (PreToolUse, PostToolUse,
+     * PostToolUseFailure, PermissionDenied).
+     *
+     * Pass `undefined` (the default) to skip all hook dispatch. When a
+     * registry is provided, the run attaches it to the `Graph` so internal
+     * nodes can fire hooks too, and clears the session in the `finally`
+     * block to prevent leaks.
+     */
+    hooks?: HookRegistry;
     returnContent?: boolean;
     tokenCounter?: TokenCounter;
     indexTokenCountMap?: Record<string, number>;
@@ -114,6 +128,12 @@ export type RunConfig = {
     calibrationRatio?: number;
     /** Skip post-stream cleanup (clearHeavyState) — useful for tests that inspect graph state after processStream */
     skipCleanup?: boolean;
+    /**
+     * Initial session state to seed the Graph's ToolSessionMap.
+     * Used to carry over code environment sessions from skill file priming
+     * at run start, so ToolNode can inject session_id + files into tool calls.
+     */
+    initialSessions?: ToolSessionMap;
 };
 export type ProvidedCallbacks = (BaseCallbackHandler | CallbackHandlerMethods)[] | undefined;
 export type TokenCounter = (message: BaseMessage) => number;

package/dist/types/types/skill.d.ts

@@ -0,0 +1,9 @@
+/** Minimal skill metadata for catalog assembly. The host provides these from its own data layer. */
+export type SkillCatalogEntry = {
+    /** Kebab-case identifier (what the model passes to SkillTool) */
+    name: string;
+    /** One-line description for the catalog listing */
+    description: string;
+    /** Optional human-readable label (UI only, not shown to model) */
+    displayTitle?: string;
+};