deepagents 1.14.2 → 1.15.0

package/dist/{langsmith--RbtjNdQ.js → langsmith-v_uskil7.js}

@@ -1,6 +1,6 @@
 import { AIMessage, HumanMessage, SystemMessage, ToolMessage, anthropicPromptCachingMiddleware, bedrockPromptCachingMiddleware, context, countTokensApproximately, createAgent, createMiddleware, humanInTheLoopMiddleware, todoListMiddleware, tool } from "langchain";
 import { ContextOverflowError } from "@langchain/core/errors";
-import { Command, REMOVE_ALL_MESSAGES, ReducedValue, StateSchema, getConfig, getCurrentTaskInput, getStore, isCommand } from "@langchain/langgraph";
+import { Command, Overwrite, REMOVE_ALL_MESSAGES, ReducedValue, StateSchema, getConfig, getCurrentTaskInput, getStore, isCommand } from "@langchain/langgraph";
 import { z } from "zod/v4";
 import micromatch from "micromatch";
 import { createHash } from "node:crypto";
@@ -9,9 +9,30 @@ import * as z$2 from "zod";
 import { z as z$1 } from "zod";
 import { initChatModel } from "langchain/chat_models/universal";
 import yaml from "yaml";
+import { Runnable, RunnableBinding } from "@langchain/core/runnables";
+import { isLangChainTool } from "@langchain/core/tools";
+import { isOpenAITool } from "@langchain/core/language_models/base";
+import { convertToOpenAIFunction } from "@langchain/core/utils/function_calling";
+import { toJsonSchema } from "@langchain/core/utils/json_schema";
+import { isInteropZodSchema } from "@langchain/core/utils/types";
 import { Client } from "@langchain/langgraph-sdk";
 import { Client as Client$1 } from "langsmith";
 import { LangSmithResourceNotFoundError, LangSmithSandboxError, SandboxClient } from "langsmith/experimental/sandbox";
+//#region src/backends/realpath.ts
+const REALPATH = Symbol.for("deepagents.realpath");
+function getRealpath(backend) {
+	if (typeof backend !== "object" || backend === null) return;
+	const fn = backend[REALPATH];
+	return typeof fn === "function" ? fn : void 0;
+}
+function setRealpath(target, fn) {
+	Object.defineProperty(target, REALPATH, {
+		value: fn,
+		enumerable: false,
+		configurable: true
+	});
+}
+//#endregion
 //#region src/backends/utils.ts
 /**
 * Shared utility functions for memory backend implementations.
@@ -643,6 +664,8 @@ function adaptBackendProtocol(backend) {
 			configurable: true
 		});
 	}
+	const realpath = getRealpath(backend);
+	if (realpath !== void 0) setRealpath(adapted, realpath);
 	const resolveBackendForPath = backend.resolveBackendForPath;
 	if (typeof resolveBackendForPath === "function") Object.defineProperty(adapted, "resolveBackendForPath", {
 		value: (path) => resolveBackendForPath.call(backend, path),
@@ -1579,11 +1602,13 @@ function validatePermissionPaths(permissions) {
 * - Non-absolute paths (must start with `/`)
 * - Paths containing `..`
 * - Paths containing `~`
+*
+* Empty and `.` segments are dropped (`/a/./b` and `/a//b` become `/a/b`).
 */
 function validatePath(raw) {
 	if (typeof raw !== "string" || raw.length === 0) throw new Error("path must be a non-empty string");
 	if (!raw.startsWith("/")) throw new Error(`path must be absolute: ${JSON.stringify(raw)}`);
-	const segments = raw.split("/").filter((s) => s.length > 0);
+	const segments = raw.split("/").filter((s) => s.length > 0 && s !== ".");
 	if (segments.includes("..")) throw new Error(`path must not contain "..": ${JSON.stringify(raw)}`);
 	if (segments.includes("~")) throw new Error(`path must not contain "~": ${JSON.stringify(raw)}`);
 	return `/${segments.join("/")}`;
@@ -1633,14 +1658,15 @@ var CompositeBackend = class {
 	sortedRoutes;
 	constructor(defaultBackend, routes) {
 		this.default = isSandboxProtocol(defaultBackend) ? adaptSandboxProtocol(defaultBackend) : adaptBackendProtocol(defaultBackend);
-		this.routes = Object.fromEntries(Object.entries(routes).map(([k, v]) => [k, isSandboxProtocol(v) ? adaptSandboxProtocol(v) : adaptBackendProtocol(v)]));
+		this.routes = Object.fromEntries(Object.entries(routes).map(([k, v]) => [k.endsWith("/") ? k : `${k}/`, isSandboxProtocol(v) ? adaptSandboxProtocol(v) : adaptBackendProtocol(v)]));
 		this.sortedRoutes = Object.entries(this.routes).sort((a, b) => b[0].length - a[0].length);
+		setRealpath(this, (path) => this.resolveRealPath(path));
 	}
 	/** Delegates to default backend's id if it is a sandbox, otherwise empty string. */
 	get id() {
 		return isSandboxBackend(this.default) ? this.default.id : "";
 	}
-	/** Route prefixes registered on this backend (e.g. `["/workspace"]`). */
+	/** Route prefixes registered on this backend, normalized to a trailing slash (e.g. `["/workspace/"]`). */
 	get routePrefixes() {
 		return Object.keys(this.routes);
 	}
@@ -1653,11 +1679,29 @@ var CompositeBackend = class {
 	static isInstance(backend) {
 		return typeof backend === "object" && backend !== null && Array.isArray(backend.routePrefixes);
 	}
-	/** Returns the backend for `path`, with the matched prefix stripped from the returned path. */
+	/**
+	* Returns the backend for `path`, with the matched prefix stripped (`/foo` → `/`).
+	* Routes match on path-segment boundaries: `/foo` matches `/foo/bar` but not `/foobar`.
+	*/
 	resolveBackendForPath(path) {
 		return this.getBackendAndKey(path);
 	}
 	/**
+	* Resolve symlinks via the backend that owns `path`, re-adding the route
+	* prefix. Returns `path` unchanged when that backend has no realpath hook.
+	*/
+	async resolveRealPath(path) {
+		for (const [routePrefix, backend] of this.sortedRoutes) if (this.isPathWithinRoute(path, routePrefix)) {
+			const realpath = getRealpath(backend);
+			if (realpath === void 0) return path;
+			const suffix = path.substring(routePrefix.length);
+			const resolved = await realpath(suffix ? "/" + suffix : "/");
+			return routePrefix.slice(0, -1) + resolved;
+		}
+		const realpath = getRealpath(this.default);
+		return realpath === void 0 ? path : await realpath(path);
+	}
+	/**
 	* Determine which backend handles this key and strip prefix.
 	*
 	* @param key - Original file path
@@ -2424,25 +2468,42 @@ function getErrorMessage$1(error) {
 	return String(error);
 }
 /**
-* Check whether `path` is permitted under `rules` for `operation`, returning an
-* error string to surface to the model (or `undefined` when allowed).
+* Resolve `canonical` through the backend's realpath hook, when it has one, and
+* re-validate the result so it is canonical for rule matching. Returns
+* `canonical` unchanged for backends without path aliasing.
+*/
+async function resolveRealPath(backend, canonical) {
+	const realpath = getRealpath(backend);
+	return realpath ? validatePath(await realpath(canonical)) : canonical;
+}
+/**
+* Check whether `path` is permitted under `rules` for `operation`.
 *
-* Never throws: an invalid path (non-absolute, or containing `..` or `~`) or a
-* denied path is a recoverable tool error, not a fatal run-ending one. Such
-* paths are rejected, never normalized, so they cannot bypass a deny rule or
-* reach the backend.
+* Returns the canonical path to hand the backend, or an error string to
+* surface to the model. The decision covers every form of the target: the
+* lexical canonical path (dot and empty segments dropped) and, when the
+* backend has a realpath hook, the symlink-resolved path it would actually
+* touch. A deny on either blocks the call.
+*
+* Never throws: an invalid path (non-absolute, or containing `..` or `~`), one
+* the backend cannot resolve, or a denied one is a recoverable tool error, not
+* a fatal run-ending one. With no rules configured, `path` is returned as-is.
 *
 * @internal
 */
-function checkPermission(rules, operation, path) {
-	if (rules.length === 0) return;
+async function checkPermission(backend, rules, operation, path) {
+	if (rules.length === 0) return { path };
 	let canonical;
+	let real;
 	try {
 		canonical = validatePath(path);
+		if (decidePathAccess(rules, operation, canonical) === "deny") return { error: `Error: permission denied for ${operation} on ${canonical}` };
+		real = await resolveRealPath(backend, canonical);
 	} catch (error) {
-		return `Error: ${getErrorMessage$1(error)}`;
+		return { error: `Error: ${getErrorMessage$1(error)}` };
 	}
-	if (decidePathAccess(rules, operation, canonical) === "deny") return `Error: permission denied for ${operation} on ${canonical}`;
+	if (real !== canonical && decidePathAccess(rules, operation, real) === "deny") return { error: `Error: permission denied for ${operation} on ${canonical} (resolves to ${real})` };
+	return { path: canonical };
 }
 /**
 * Build an error {@link ToolMessage} for a rejected or denied path. Returning a
@@ -2615,27 +2676,56 @@ function parentPath(path) {
 	if (parts.length <= 1) return "/";
 	return `/${parts.slice(0, -1).join("/")}`;
 }
+/**
+* Resolve the path a delete of `target` would actually remove. Backends unlink
+* a symlink leaf rather than following it, so only the parent is resolved.
+*/
+async function resolveDeleteRealPath(backend, target) {
+	const parts = posixParts(target);
+	if (parts.length === 0) return resolveRealPath(backend, target);
+	return validatePath(`${await resolveRealPath(backend, parentPath(target))}/${parts[parts.length - 1]}`);
+}
 function supportsDelete(backend) {
 	return typeof backend.delete === "function";
 }
 /**
 * Filter a list of filesystem entries to those the rules permit.
 *
-* `getPath` extracts the absolute path from each entry. Entries with
-* unparsable paths are included (not silently dropped). Returns the
-* original array unchanged when `rules` is empty.
+* `getPath` extracts the absolute path from each entry. Each entry is checked
+* on its canonical path and, when the backend has a realpath hook, on its
+* symlink-resolved path. Entries with unparsable paths are included; entries
+* whose path cannot be resolved are dropped.
+* Returns the original array unchanged when `rules` is empty.
 *
 * @internal
 */
-function filterByPermissions(entries, rules, operation, getPath) {
+async function filterByPermissions(backend, entries, rules, operation, getPath) {
 	if (rules.length === 0) return entries;
-	return entries.filter((entry) => {
+	const decisions = /* @__PURE__ */ new Map();
+	const isPermitted = async (rawPath) => {
+		let canonical;
 		try {
-			return decidePathAccess(rules, operation, validatePath(getPath(entry))) !== "deny";
+			canonical = validatePath(rawPath);
 		} catch {
 			return true;
 		}
-	});
+		if (decidePathAccess(rules, operation, canonical) === "deny") return false;
+		try {
+			return decidePathAccess(rules, operation, await resolveRealPath(backend, canonical)) !== "deny";
+		} catch {
+			return false;
+		}
+	};
+	const permitted = await Promise.all(entries.map((entry) => {
+		const rawPath = getPath(entry);
+		let decision = decisions.get(rawPath);
+		if (decision === void 0) {
+			decision = isPermitted(rawPath);
+			decisions.set(rawPath, decision);
+		}
+		return decision;
+	}));
+	return entries.filter((_, index) => permitted[index]);
 }
 const LS_TOOL_DESCRIPTION = context`
   Lists all files in a directory.
@@ -2723,13 +2813,13 @@ function getExecuteToolDescription(hasGrep, hasGlob) {
 function createLsTool(backend, options) {
 	const { customDescription, permissions } = options;
 	return tool(async (input, runtime) => {
-		const permissionError = checkPermission(permissions, "read", input.path ?? "/");
-		if (permissionError !== void 0) return toolError(runtime, "ls", permissionError);
 		const resolvedBackend = await resolveBackend(backend, runtime);
 		const path = input.path || "/";
-		const lsResult = await resolvedBackend.ls(path);
+		const permission = await checkPermission(resolvedBackend, permissions, "read", path);
+		if (permission.error !== void 0) return toolError(runtime, "ls", permission.error);
+		const lsResult = await resolvedBackend.ls(permission.path);
 		if (lsResult.error) return `Error listing files: ${lsResult.error}`;
-		const infos = filterByPermissions(lsResult.files ?? [], permissions, "read", (info) => info.path);
+		const infos = await filterByPermissions(resolvedBackend, lsResult.files ?? [], permissions, "read", (info) => info.path);
 		if (infos.length === 0) return `No files found in ${path}`;
 		const lines = [];
 		for (const info of infos) if (info.is_dir) lines.push(`${info.path} (directory)`);
@@ -2752,23 +2842,17 @@ function createLsTool(backend, options) {
 function createReadFileTool(backend, options) {
 	const { customDescription, toolTokenLimitBeforeEvict, permissions } = options;
 	return tool(async (input, runtime) => {
-		const permissionError = checkPermission(permissions, "read", input.file_path);
-		if (permissionError !== void 0) return toolError(runtime, "read_file", permissionError);
 		const resolvedBackend = await resolveBackend(backend, runtime);
+		const permission = await checkPermission(resolvedBackend, permissions, "read", input.file_path);
+		if (permission.error !== void 0) return toolError(runtime, "read_file", permission.error);
 		const { file_path, offset: requestedOffset = 0, limit: requestedLimit = 100 } = input;
 		const { offset, limit } = normalizeReadPagination(requestedOffset, requestedLimit);
-		const readResult = await resolvedBackend.read(file_path, offset, limit);
-		if (readResult.error) return [{
-			type: "text",
-			text: `Error: ${readResult.error}`
-		}];
+		const readResult = await resolvedBackend.read(permission.path, offset, limit);
+		if (readResult.error) return toolError(runtime, "read_file", `Error: ${readResult.error}`);
 		const mimeType = readResult.mimeType ?? getMimeType(file_path);
 		if (!isTextMimeType(mimeType)) {
 			const binaryContent = readResult.content;
-			if (!binaryContent) return [{
-				type: "text",
-				text: `Error: expected binary content for '${file_path}'`
-			}];
+			if (!binaryContent) return toolError(runtime, "read_file", `Error: expected binary content for '${file_path}'`);
 			let base64Data;
 			if (typeof binaryContent === "string") base64Data = binaryContent;
 			else if (ArrayBuffer.isView(binaryContent)) base64Data = Buffer.from(binaryContent).toString("base64");
@@ -2777,10 +2861,7 @@ function createReadFileTool(backend, options) {
 				base64Data = Buffer.from(new Uint8Array(values)).toString("base64");
 			}
 			const sizeBytes = Math.ceil(base64Data.length * 3 / 4);
-			if (sizeBytes > 10485760) return [{
-				type: "text",
-				text: `Error: file too large to read (${Math.round(sizeBytes / 1048576)}MB exceeds ${MAX_BINARY_READ_SIZE_BYTES / 1048576}MB limit for binary files)`
-			}];
+			if (sizeBytes > 10485760) return toolError(runtime, "read_file", `Error: file too large to read (${Math.round(sizeBytes / 1048576)}MB exceeds ${MAX_BINARY_READ_SIZE_BYTES / 1048576}MB limit for binary files)`);
 			if (mimeType.startsWith("image/")) return [{
 				type: "image",
 				mimeType,
@@ -2846,11 +2927,11 @@ function createReadFileTool(backend, options) {
 function createWriteFileTool(backend, options) {
 	const { customDescription, permissions } = options;
 	return tool(async (input, runtime) => {
-		const permissionError = checkPermission(permissions, "write", input.file_path);
-		if (permissionError !== void 0) return toolError(runtime, "write_file", permissionError);
 		const resolvedBackend = await resolveBackend(backend, runtime);
+		const permission = await checkPermission(resolvedBackend, permissions, "write", input.file_path);
+		if (permission.error !== void 0) return toolError(runtime, "write_file", permission.error);
 		const { file_path, content } = input;
-		const result = await resolvedBackend.write(file_path, content);
+		const result = await resolvedBackend.write(permission.path, content);
 		if (result.error) return result.error;
 		const message = new ToolMessage({
 			content: `Successfully wrote to '${file_path}'`,
@@ -2878,11 +2959,11 @@ function createWriteFileTool(backend, options) {
 function createEditFileTool(backend, options) {
 	const { customDescription, permissions } = options;
 	return tool(async (input, runtime) => {
-		const permissionError = checkPermission(permissions, "write", input.file_path);
-		if (permissionError !== void 0) return toolError(runtime, "edit_file", permissionError);
 		const resolvedBackend = await resolveBackend(backend, runtime);
+		const permission = await checkPermission(resolvedBackend, permissions, "write", input.file_path);
+		if (permission.error !== void 0) return toolError(runtime, "edit_file", permission.error);
 		const { file_path, old_string, new_string, replace_all = false } = input;
-		const result = await resolvedBackend.edit(file_path, old_string, new_string, replace_all);
+		const result = await resolvedBackend.edit(permission.path, old_string, new_string, replace_all);
 		if (result.error) return result.error;
 		const message = new ToolMessage({
 			content: `Successfully replaced ${result.occurrences} occurrence(s) in '${file_path}'`,
@@ -2922,6 +3003,17 @@ function createDeleteTool(backend, options) {
 		const hasDescendants = await deleteTargetMayHaveDescendants(resolvedBackend, validatedPath, permissions.length > 0);
 		const denyingPatterns = findDeleteDenyPatterns(permissions, validatedPath, hasDescendants);
 		if (denyingPatterns.length > 0) return toolError(runtime, "delete", `Error: permission denied for write on ${validatedPath} (matches deny rule(s): ${denyingPatterns.join(", ")})`);
+		if (permissions.length > 0) {
+			let realTarget;
+			try {
+				realTarget = await resolveDeleteRealPath(resolvedBackend, validatedPath);
+			} catch (error) {
+				return toolError(runtime, "delete", `Error: ${getErrorMessage$1(error)}`);
+			}
+			if (realTarget !== validatedPath) {
+				if (findDeleteDenyPatterns(permissions, realTarget, hasDescendants).length > 0) return toolError(runtime, "delete", `Error: permission denied for write on ${validatedPath} (resolves to ${realTarget})`);
+			}
+		}
 		if (!supportsDelete(resolvedBackend)) return toolError(runtime, "delete", `Error: deletion is not available for '${validatedPath}'.`);
 		const result = await resolvedBackend.delete(validatedPath);
 		if (result.error) return toolError(runtime, "delete", result.error);
@@ -2948,13 +3040,13 @@ function createDeleteTool(backend, options) {
 function createGlobTool(backend, options) {
 	const { customDescription, permissions } = options;
 	return tool(async (input, runtime) => {
-		const permissionError = checkPermission(permissions, "read", input.path ?? "/");
-		if (permissionError !== void 0) return toolError(runtime, "glob", permissionError);
 		const resolvedBackend = await resolveBackend(backend, runtime);
-		const { pattern, path } = input;
-		const globResult = await resolvedBackend.glob(pattern, path);
+		const { pattern } = input;
+		const permission = await checkPermission(resolvedBackend, permissions, "read", input.path ?? "/");
+		if (permission.error !== void 0) return toolError(runtime, "glob", permission.error);
+		const globResult = await resolvedBackend.glob(pattern, input.path === void 0 ? void 0 : permission.path);
 		if (globResult.error) return `Error finding files: ${globResult.error}`;
-		const infos = filterByPermissions(globResult.files ?? [], permissions, "read", (info) => info.path);
+		const infos = await filterByPermissions(resolvedBackend, globResult.files ?? [], permissions, "read", (info) => info.path);
 		if (infos.length === 0) return `No files found matching pattern '${pattern}'`;
 		const result = truncateIfTooLong(infos.map((info) => info.path));
 		if (Array.isArray(result)) return result.join("\n");
@@ -2974,14 +3066,14 @@ function createGlobTool(backend, options) {
 function createGrepTool(backend, options) {
 	const { customDescription, permissions, includeExecution, grepMaxCount } = options;
 	return tool(async (input, runtime) => {
-		const permissionError = checkPermission(permissions, "read", input.path ?? "/");
-		if (permissionError !== void 0) return toolError(runtime, "grep", permissionError);
 		const resolvedBackend = await resolveBackend(backend, runtime);
 		const { pattern, path = "/", glob = null, output_mode = "content" } = input;
+		const permission = await checkPermission(resolvedBackend, permissions, "read", path);
+		if (permission.error !== void 0) return toolError(runtime, "grep", permission.error);
 		const maxCount = input.max_count ?? grepMaxCount;
-		const result = await resolvedBackend.grep(pattern, path, glob, maxCount);
+		const result = await resolvedBackend.grep(pattern, permission.path, glob, maxCount);
 		if (result.error) return result.error;
-		const matches = filterByPermissions(result.matches ?? [], permissions, "read", (m) => m.path);
+		const matches = await filterByPermissions(resolvedBackend, result.matches ?? [], permissions, "read", (m) => m.path);
 		if (matches.length === 0) return `No matches found for pattern '${pattern}'`;
 		const truncated = truncateIfTooLong(formatGrepMatches(matches, output_mode));
 		let content = typeof truncated === "string" ? truncated : truncated.join("\n");
@@ -4173,10 +4265,12 @@ const EXCLUDED_STATE_KEYS = [
 	"todos",
 	"structuredResponse",
 	"skillsMetadata",
+	"pinnedSkills",
 	"memoryContents",
 	...CALL_COUNT_STATE_KEYS,
 	"_summarizationEvent",
 	"_summarizationSessionId",
+	"_skillToolsDisclosed",
 	FORKED_CONTEXT_KEY
 ];
 /**
@@ -4195,9 +4289,11 @@ const EXCLUDED_STATE_KEYS = [
 */
 const FORK_EXCLUDED_STATE_KEYS = [
 	"structuredResponse",
+	"pinnedSkills",
 	...CALL_COUNT_STATE_KEYS,
 	"_summarizationEvent",
-	"_summarizationSessionId"
+	"_summarizationSessionId",
+	"_skillToolsDisclosed"
 ];
 /**
 * Default description for the general-purpose subagent.
@@ -4640,7 +4736,8 @@ function patchDanglingToolCalls(messages) {
 				patchedMessages.push(new ToolMessage({
 					content: toolMsg,
 					name: toolCall.name,
-					tool_call_id: toolCall.id
+					tool_call_id: toolCall.id,
+					status: "error"
 				}));
 			}
 		}
@@ -5082,6 +5179,46 @@ function createMemoryMiddleware(options) {
 	});
 }
 //#endregion
+//#region src/errors.ts
+const CONFIGURATION_ERROR_SYMBOL = Symbol.for("deepagents.configuration_error");
+/**
+* Thrown when `createDeepAgent` receives invalid configuration.
+*
+* Follows the same pattern as {@link SandboxError}: a human-readable
+* `message`, a structured `code` for programmatic handling, and a
+* static `isInstance` guard that works across realms.
+*
+* @example
+* ```typescript
+* try {
+*   createDeepAgent({ tools: [myTool] });
+* } catch (error) {
+*   if (ConfigurationError.isInstance(error)) {
+*     switch (error.code) {
+*       case "TOOL_NAME_COLLISION":
+*         console.error("Rename your tool:", error.message);
+*         break;
+*     }
+*   }
+* }
+* ```
+*/
+var ConfigurationError = class ConfigurationError extends Error {
+	code;
+	cause;
+	[CONFIGURATION_ERROR_SYMBOL] = true;
+	name = "ConfigurationError";
+	constructor(message, code, cause) {
+		super(message);
+		this.code = code;
+		this.cause = cause;
+		Object.setPrototypeOf(this, ConfigurationError.prototype);
+	}
+	static isInstance(error) {
+		return typeof error === "object" && error !== null && error[CONFIGURATION_ERROR_SYMBOL] === true;
+	}
+};
+//#endregion
 //#region src/middleware/skills.ts
 /**
 * Backend-agnostic skills middleware for loading agent skills from any backend.
@@ -5141,6 +5278,10 @@ const SKILL_MODULE_EXTENSIONS = [
 	".jsx",
 	".tsx"
 ];
+/** `SKILL.md` frontmatter `metadata` key listing the skill's include names, space-separated. */
+const INCLUDE_TOOLS_KEY = "include_tools";
+/** YAML frontmatter between `---` delimiters at the start of a `SKILL.md`. */
+const FRONTMATTER_PATTERN = /^---\s*\n([\s\S]*?)\n---\s*\n/;
 /**
 * Zod schema for a single skill metadata entry.
 */
@@ -5182,11 +5323,52 @@ const SkillMetadataEntrySchema = z$1.object({
 */
 const skillsMetadataValue = z$1.array(SkillMetadataEntrySchema).nullish();
 /**
+* State value for a middleware's `pinnedSkills` field: the names of skills to
+* pin.
+*
+* The next time the skills middleware's `beforeModel` runs, before a model
+* call, each named skill's `SKILL.md`, without its frontmatter, is appended to
+* the conversation as its own `HumanMessage`, in the order named. The message
+* is a snapshot: editing the file later doesn't change it, and naming the
+* skill again appends a new copy.
+*
+* Names only, matched exactly against the loaded skills. A name that isn't
+* loaded, or whose `SKILL.md` can't be read, is skipped without an error. The
+* key is cleared once consumed, so a later run pins nothing unless it names
+* skills again. Writes in the same step add up, so parallel tool calls can
+* each pin skills by returning a `Command`.
+*
+* Like {@link skillsMetadataValue}, treat the value as opaque. A middleware
+* declares it on its state schema to set `pinnedSkills` from its own hooks.
+*
+* @example
+* ```typescript
+* import { createMiddleware } from "langchain";
+* import { StateSchema } from "@langchain/langgraph";
+* import { pinnedSkillsValue } from "deepagents";
+*
+* const routeSkills = createMiddleware({
+*   name: "RouteSkills",
+*   stateSchema: new StateSchema({ pinnedSkills: pinnedSkillsValue }),
+*   beforeAgent: (state) => ({ pinnedSkills: skillsFor(state.messages) }),
+* });
+* ```
+*/
+const pinnedSkillsValue = new ReducedValue(z$1.array(z$1.string()).default(() => []), { reducer: (stored, written) => [...stored ?? [], ...written ?? []] });
+/**
 * State schema for skills middleware.
 */
 const SkillsStateSchema = new StateSchema({
 	skillsMetadata: skillsMetadataValue,
-	files: filesValue
+	pinnedSkills: pinnedSkillsValue,
+	files: filesValue,
+	/**
+	* The skill tools disclosed to the latest model call, each mapped to the
+	* include name that produced it, for the tool-time gate. Written on every
+	* model call of a skills middleware with skill tools. The last write wins,
+	* so a model call retried within one step can write it again.
+	*/
+	_skillToolsDisclosed: new ReducedValue(z$1.record(z$1.string(), z$1.string()).optional(), { reducer: (_previous, next) => next })
 });
 /**
 * Skills System Documentation prompt template.
@@ -5288,7 +5470,8 @@ function validateSkillName(name, directoryName) {
 *
 * YAML parsing can return any type for the `metadata` key. This ensures the
 * value in {@link SkillMetadata} is always a `Record<string, string>` by
-* coercing via `String()` and rejecting non-object inputs.
+* coercing via `String()` and rejecting non-object inputs. It also warns when
+* `include_tools` isn't a space-separated string of tool names.
 *
 * @param raw - Raw value from `frontmatterData.metadata`.
 * @param skillPath - Path to the `SKILL.md` file (for warning messages).
@@ -5299,6 +5482,8 @@ function validateMetadata(raw, skillPath) {
 		if (raw) console.warn(`Ignoring non-object metadata in ${skillPath} (got ${typeof raw})`);
 		return {};
 	}
+	const includeTools = raw[INCLUDE_TOOLS_KEY];
+	if (Array.isArray(includeTools) || typeof includeTools === "string" && includeTools.includes(",")) console.warn(`metadata.include_tools in ${skillPath} should be a space-separated string of tool names; got ${JSON.stringify(includeTools)}`);
 	const result = {};
 	for (const [k, v] of Object.entries(raw)) result[String(k)] = String(v);
 	return result;
@@ -5336,7 +5521,7 @@ function parseSkillMetadataFromContent(content, skillPath, directoryName) {
 		console.warn(`Skipping ${skillPath}: content too large (${content.length} bytes)`);
 		return null;
 	}
-	const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
+	const match = content.match(FRONTMATTER_PATTERN);
 	if (!match) {
 		console.warn(`Skipping ${skillPath}: no valid YAML frontmatter found`);
 		return null;
@@ -5455,6 +5640,61 @@ async function listSkillsFromBackend(backend, sourcePath) {
 	return skills;
 }
 /**
+* Load the skills in every source, in order. A later source's skill replaces
+* an earlier one of the same name.
+*/
+async function loadSkills(backend, sources) {
+	const allSkills = /* @__PURE__ */ new Map();
+	for (const sourcePath of sources) try {
+		const skills = await listSkillsFromBackend(backend, sourcePath);
+		for (const skill of skills) allSkills.set(skill.name, skill);
+	} catch (error) {
+		console.debug(`[BackendSkillsMiddleware] Failed to load skills from ${sourcePath}:`, error);
+	}
+	return Array.from(allSkills.values());
+}
+/**
+* Return a message pinning each skill `names` refers to, in first-seen order.
+*
+* Skips a name that isn't in `skills`, and a skill whose `SKILL.md` is
+* missing, unreadable, empty, or larger than {@link MAX_SKILL_FILE_SIZE}.
+*/
+async function buildPinnedSkillMessages(backend, names, skills) {
+	const adaptedBackend = adaptBackendProtocol(backend);
+	const skillsByName = new Map(skills.map((skill) => [skill.name, skill]));
+	const skillsToPin = [...new Set(names)].flatMap((name) => {
+		const skill = skillsByName.get(name);
+		return skill === void 0 ? [] : [skill];
+	});
+	const contents = await Promise.all(skillsToPin.map((skill) => readFileFromBackend(adaptedBackend, skill.path).catch(() => null)));
+	return skillsToPin.flatMap((skill, i) => {
+		const content = contents[i];
+		if (!content || content.length > 10485760) return [];
+		return [buildPinnedSkillMessage(skill, content)];
+	});
+}
+/** Return the message pinning `skill`, carrying its `SKILL.md` `content` without frontmatter. */
+function buildPinnedSkillMessage(skill, content) {
+	const body = content.replace(FRONTMATTER_PATTERN, "").trimEnd();
+	const name = escapeXmlAttribute(skill.name);
+	const path = escapeXmlAttribute(skill.path);
+	return new HumanMessage$1({
+		content: `<skill name="${name}" path="${path}">\n${body}\n</skill>`,
+		additional_kwargs: {
+			lc_source: "pinned_skill",
+			skill: {
+				name: skill.name,
+				path: skill.path,
+				description: skill.description
+			}
+		}
+	});
+}
+/** Escape `value` for a double-quoted XML attribute. */
+function escapeXmlAttribute(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+/**
 * Format skills locations for display in system prompt.
 * Shows priority indicator for the last source (highest priority).
 */
@@ -5514,6 +5754,336 @@ function validateModulePath(raw) {
 	if (!endsWithModuleExtension(normalized)) return;
 	return normalized;
 }
+/** Tool `extras` key (and provider field) that withholds a tool's schema until searched for. */
+const DEFER_LOADING = "defer_loading";
+/**
+* Model ID prefixes that accept an inline `tool_definition` mid-conversation.
+*
+* `@langchain/anthropic` sends any mid-conversation system message in place,
+* without gating on the model, so this list is the only guard.
+*/
+const ANTHROPIC_INLINE_TOOL_MODELS = [
+	"claude-opus-5",
+	"claude-fable-5",
+	"claude-mythos-5",
+	"claude-opus-4-8"
+];
+/** Models whose Responses API accepts an `additional_tools` input item, matched with or without a `-` suffix such as a snapshot date. */
+const OPENAI_INLINE_TOOL_MODELS = ["gpt-6", "gpt-5.6"];
+/** Root `input_schema` keys the Anthropic API rejects, failing the whole request. */
+const ANTHROPIC_ROOT_COMBINATORS = [
+	"oneOf",
+	"anyOf",
+	"allOf"
+];
+/** `extras` keys `ChatAnthropic` copies into a tool's definition, bar the ones a disclosure must never carry. */
+const ANTHROPIC_DEFINITION_EXTRAS = [
+	"input_examples",
+	"allowed_callers",
+	"strict"
+];
+/**
+* Return the resolver the skills middleware's `tools` option stands for.
+*
+* A list is validated, then resolved by exact name.
+*
+* @throws {ConfigurationError} If `tools` is neither a list nor a function,
+*   or a list entry isn't a client tool or repeats a name.
+*/
+function toSkillToolResolver(tools) {
+	if (tools != null && !Array.isArray(tools)) {
+		if (typeof tools !== "function") throw new ConfigurationError(`tools must be an array of tools or a resolver function, got ${typeof tools}; wrap a single tool in an array`, "SKILL_TOOLS_UNSUPPORTED_TYPE");
+		return tools;
+	}
+	const entries = tools ?? [];
+	if (!entries.every(isClientTool)) throw new ConfigurationError("tools entries must be client tools; provider-native tool objects are not supported", "SKILL_TOOLS_UNSUPPORTED_TYPE");
+	const names = entries.map((t) => t.name);
+	const duplicates = [...new Set(names.filter((n, i) => names.indexOf(n) !== i))].sort();
+	if (duplicates.length > 0) throw new ConfigurationError(`tools contains duplicate tool name(s): ${duplicates.join(", ")}`, "SKILL_TOOLS_DUPLICATE_NAME");
+	const byName = new Map(entries.map((t) => [t.name, t]));
+	return (name) => byName.has(name) ? [byName.get(name)] : [];
+}
+/** Whether `value` is a runnable client tool rather than a provider-native or plain object. */
+function isClientTool(value) {
+	return Runnable.isRunnable(value) && typeof value.name === "string";
+}
+/**
+* Call `resolver` for one include name, keeping the first of each tool name.
+*
+* @throws {TypeError} If the resolver returns something other than an array
+*   of client tools.
+*/
+async function callSkillToolResolver(resolver, includeName, runtime) {
+	const result = await resolver(includeName, runtime);
+	if (!Array.isArray(result)) throw new TypeError(`skill tool resolver must return an array of tools for '${includeName}', got ${typeof result}`);
+	const tools = /* @__PURE__ */ new Map();
+	for (const item of result) {
+		if (!isClientTool(item)) throw new TypeError(`skill tool resolver returned a non-tool ${typeof item} for '${includeName}'; expected tool instances`);
+		if (!tools.has(item.name)) tools.set(item.name, item);
+	}
+	return [...tools.values()];
+}
+/**
+* Return every successful `read_file` or pin of a `SKILL.md` that lists
+* tools, in message order.
+*
+* The read's or pin's path must equal the skill's path exactly, as the skills
+* listing shows it. Any `offset` or `limit` counts, and so does a result whose
+* content was later truncated or compacted, since only the call and the
+* result's status are read.
+*/
+function findSkillReads(messages, skills) {
+	const skillsByPath = /* @__PURE__ */ new Map();
+	for (const skill of skills) {
+		const value = skill.metadata?.[INCLUDE_TOOLS_KEY];
+		const includeNames = typeof value === "string" ? value.split(/\s+/).filter(Boolean) : [];
+		if (includeNames.length > 0) skillsByPath.set(skill.path, { includeNames });
+	}
+	if (skillsByPath.size === 0) return [];
+	const readPaths = /* @__PURE__ */ new Map();
+	for (const message of messages) {
+		if (!AIMessage$1.isInstance(message)) continue;
+		for (const toolCall of message.tool_calls ?? []) if (toolCall.name === "read_file" && toolCall.id) readPaths.set(toolCall.id, toolCall.args?.file_path ?? toolCall.args?.path);
+	}
+	const reads = [];
+	messages.forEach((message, index) => {
+		let path;
+		if (ToolMessage$1.isInstance(message) && message.status !== "error") path = readPaths.get(message.tool_call_id);
+		else if (HumanMessage$1.isInstance(message) && message.additional_kwargs?.lc_source === "pinned_skill") path = message.additional_kwargs.skill?.path;
+		else return;
+		const skill = typeof path === "string" ? skillsByPath.get(path) : void 0;
+		if (skill !== void 0) reads.push({
+			index,
+			...skill
+		});
+	});
+	return reads;
+}
+/** Return a request tool's name, whether it is a tool instance or a provider object. */
+function toolName(tool) {
+	if (isOpenAITool(tool)) return tool.function.name;
+	return typeof tool.name === "string" ? tool.name : void 0;
+}
+/**
+* Disclose the tools the read skills' include names produce to one model call.
+*
+* Returns the request to send, and the record of the skill tools it
+* discloses, for the tool-time gate.
+*/
+async function discloseSkillTools(request, reads, resolver) {
+	const requestTools = /* @__PURE__ */ new Map();
+	for (const tool of request.tools) {
+		const name = toolName(tool);
+		if (name !== void 0) requestTools.set(name, tool);
+	}
+	const names = [...new Set(reads.flatMap((read) => read.includeNames.filter((name) => !requestTools.has(name))))];
+	const tools = await Promise.all(names.map((name) => callSkillToolResolver(resolver, name, request.runtime)));
+	const disclosed = planDisclosure(reads, requestTools, new Map(names.map((name, i) => [name, tools[i]])));
+	if (disclosed.size === 0) return {
+		request,
+		record: {}
+	};
+	const chatModel = await resolveChatModel(request.model, request.runtime);
+	if (llmType(chatModel) === "anthropic") withholdRootCombinatorTools(disclosed);
+	const gatedNames = [...disclosed.keys()].filter((name) => disclosed.get(name).includeName !== void 0).sort();
+	const record = Object.fromEntries(gatedNames.map((name) => [name, disclosed.get(name).includeName]));
+	if (disclosed.size === 0) return {
+		request,
+		record
+	};
+	const build = inlineBlockBuilder(chatModel);
+	if (build !== void 0) return {
+		request: {
+			...request,
+			messages: discloseInMessages(request.messages, disclosed, build)
+		},
+		record
+	};
+	return {
+		request: {
+			...request,
+			tools: discloseInTools(request.tools, disclosed, gatedNames)
+		},
+		record
+	};
+}
+/**
+* Classify what each read skill's include names produce, anchoring each tool
+* at the earliest read producing it.
+*
+* An include name that matches a request tool's name produces that tool; any
+* other produces what the resolver returned for it. A produced tool whose name
+* a request tool has wins as that request tool, because it's the one that
+* runs: a deferred one is disclosed early, and a bound one adds nothing, since
+* the model already sees it. Tools are matched by name, never by identity,
+* because outer middleware such as tool search replaces the request's tools
+* with copies.
+*/
+function planDisclosure(reads, requestTools, resolved) {
+	const disclosed = /* @__PURE__ */ new Map();
+	const discloseIfDeferred = (name, anchor) => {
+		const entry = requestTools.get(name);
+		if (!disclosed.has(name) && isLangChainTool(entry) && entry.extras?.[DEFER_LOADING] === true) disclosed.set(name, {
+			tool: entry,
+			anchor
+		});
+	};
+	for (const { index, includeNames } of reads) for (const includeName of includeNames) {
+		if (requestTools.has(includeName)) {
+			discloseIfDeferred(includeName, index);
+			continue;
+		}
+		for (const tool of resolved.get(includeName) ?? []) {
+			if (disclosed.has(tool.name)) continue;
+			if (requestTools.has(tool.name)) discloseIfDeferred(tool.name, index);
+			else disclosed.set(tool.name, {
+				tool,
+				anchor: index,
+				includeName
+			});
+		}
+	}
+	return disclosed;
+}
+/**
+* Withhold each disclosed tool whose root input schema uses `oneOf`, `anyOf`
+* or `allOf`, which the Anthropic API rejects, failing the whole request, in
+* `tools` and inline alike. Withholding it on every path keeps the record
+* equal to what the model was shown.
+*/
+function withholdRootCombinatorTools(disclosed) {
+	for (const [name, { tool }] of disclosed) {
+		const schema = anthropicDefinition(tool).input_schema;
+		const keys = ANTHROPIC_ROOT_COMBINATORS.filter((key) => typeof schema === "object" && schema !== null && Object.prototype.hasOwnProperty.call(schema, key));
+		if (keys.length > 0) {
+			console.warn(`Not disclosing tool '${name}': its input_schema has a top-level ${keys.join("/")}, which the Anthropic API does not support`);
+			disclosed.delete(name);
+		}
+	}
+}
+/**
+* Insert one `SystemMessage` per insertion point, carrying the tools anchored
+* there, for models that accept tool definitions mid-conversation.
+*
+* Each message lands at the same index with the same bytes on every call while
+* its anchor stays visible, so the provider's cached prefix survives.
+*/
+function discloseInMessages(messages, disclosed, build) {
+	const namesByIndex = /* @__PURE__ */ new Map();
+	for (const [name, { anchor }] of disclosed) {
+		let index = anchor + 1;
+		while (index < messages.length) {
+			const message = messages[index];
+			const emptyReply = AIMessage$1.isInstance(message) && message.content.length === 0 && !message.tool_calls?.length;
+			if (!ToolMessage$1.isInstance(message) && !HumanMessage$1.isInstance(message) && !emptyReply) break;
+			index += 1;
+		}
+		namesByIndex.set(index, [...namesByIndex.get(index) ?? [], name]);
+	}
+	const result = [...messages];
+	for (const index of [...namesByIndex.keys()].sort((a, b) => b - a)) {
+		const blocks = namesByIndex.get(index).sort().map((name) => build(disclosed.get(name).tool));
+		result.splice(index, 0, new SystemMessage$1({ content: blocks }));
+	}
+	return result;
+}
+/**
+* Return `requestTools` with deferred disclosures undeferred and skill tools
+* appended, for models that can't take tool definitions mid-conversation.
+*
+* A deferred tool is replaced by a plain spec rather than a copy: `createAgent`
+* rejects a request that swaps a registered tool for another instance of the
+* same name, and doesn't validate plain objects.
+*/
+function discloseInTools(requestTools, disclosed, gatedNames) {
+	return [...requestTools.map((tool) => {
+		const name = toolName(tool);
+		const entry = name === void 0 ? void 0 : disclosed.get(name);
+		if (entry?.tool !== tool || entry.includeName !== void 0) return tool;
+		const { description, schema, extras = {} } = entry.tool;
+		const { [DEFER_LOADING]: _deferLoading, ...rest } = extras;
+		return {
+			name,
+			description,
+			schema,
+			extras: rest
+		};
+	}), ...gatedNames.map((name) => disclosed.get(name).tool)];
+}
+/** Return the model inside a `bind()` / `withConfig()` wrapper; chained calls merge into one. */
+function unwrapBinding(model) {
+	return RunnableBinding.isRunnableBinding(model) ? model.bound : model;
+}
+/**
+* Return the concrete chat model a request will call.
+*
+* Resolves a `ConfigurableModel`, which a string `model` always becomes, to
+* the instance it will call with this run's `configurable`. Without
+* configurable overrides that's the instance cached at creation: the instance
+* cache is keyed on the whole config, so passing `configurable`
+* unconditionally would build one per thread.
+*/
+async function resolveChatModel(model, runtime) {
+	const current = unwrapBinding(model);
+	if (current?._queuedMethodOperations === void 0 || typeof current._getModelInstance !== "function") return current;
+	const configurable = runtime.configurable ?? {};
+	const overrides = current._modelParams?.({ configurable }) ?? {};
+	return unwrapBinding(Object.keys(overrides).length > 0 ? await current._getModelInstance({ configurable }) : await current._getModelInstance());
+}
+/** Return a chat model's `_llmType()`, which tells providers apart. */
+function llmType(model) {
+	const fn = model?._llmType;
+	return typeof fn === "function" ? fn.call(model) : void 0;
+}
+/**
+* Return how `chatModel` is given a tool mid-conversation, or `undefined` if
+* it can't be.
+*
+* The one place that decides support, so a model-profile capability can
+* replace the allowlists later.
+*/
+function inlineBlockBuilder(chatModel) {
+	const { model: name, useResponsesApi } = chatModel;
+	if (typeof name !== "string") return void 0;
+	const type = llmType(chatModel);
+	if (type === "anthropic" && ANTHROPIC_INLINE_TOOL_MODELS.some((prefix) => name.startsWith(prefix))) return anthropicToolAddition;
+	if (type === "openai" && useResponsesApi === true && OPENAI_INLINE_TOOL_MODELS.some((model) => name === model || name.startsWith(`${model}-`))) return openaiAdditionalTools;
+}
+/**
+* Return the definition `ChatAnthropic` sends in `tools` for `tool`, without
+* `defer_loading` (a deferred definition would stay withheld) or
+* `cache_control` (a stray marker uses up a breakpoint).
+*/
+function anthropicDefinition(tool) {
+	const definition = {
+		name: tool.name,
+		description: tool.description,
+		input_schema: isInteropZodSchema(tool.schema) ? toJsonSchema(tool.schema) : tool.schema
+	};
+	for (const key of ANTHROPIC_DEFINITION_EXTRAS) if (tool.extras?.[key] !== void 0) definition[key] = tool.extras[key];
+	return definition;
+}
+/** Build the Anthropic `tool_addition` block carrying `tool`'s full definition. */
+function anthropicToolAddition(tool) {
+	return {
+		type: "tool_addition",
+		tool: {
+			type: "tool_definition",
+			definition: anthropicDefinition(tool)
+		}
+	};
+}
+/** Build the OpenAI Responses `additional_tools` item carrying `tool`'s function schema. */
+function openaiAdditionalTools(tool) {
+	return {
+		type: "additional_tools",
+		role: "developer",
+		tools: [{
+			type: "function",
+			...convertToOpenAIFunction(tool)
+		}]
+	};
+}
 /**
 * Create backend-agnostic middleware for loading and exposing agent skills.
 *
@@ -5537,8 +6107,62 @@ function validateModulePath(raw) {
 * invalidate from any hook — including mid-run, from `afterModel` — and see
 * the fresh list on the following call. See {@link skillsMetadataValue}.
 *
+* To guarantee the model gets a skill's instructions, for example when the
+* user names it, pass its name in `pinnedSkills`. Before the next model call,
+* each named skill's `SKILL.md`, without its frontmatter, is appended to the
+* conversation as its own `HumanMessage`, with `additional_kwargs.lc_source`
+* set to `"pinned_skill"` and the skill's `name`, `path` and `description`
+* under `additional_kwargs.skill`:
+*
+* ```ts
+* await agent.invoke(
+*   {
+*     messages: [new HumanMessage("/write-tests /house-style for auth.py")],
+*     pinnedSkills: ["write-tests", "house-style"],
+*   },
+*   config,
+* );
+* ```
+*
+* Pins resolve against the skills loaded for the thread, so reset
+* `skillsMetadata` in the same input to pin a skill added since. See
+* {@link pinnedSkillsValue}.
+*
+* ## Skill tools
+*
+* A skill can list the tools its instructions use, separated by spaces, under
+* `metadata.include_tools` in its `SKILL.md` frontmatter:
+*
+* ```yaml
+* metadata:
+*   include_tools: create_customer_request list_customer_requests
+* ```
+*
+* Pass those tools as `tools`, either as an array or as a
+* {@link SkillToolResolver} that looks them up by name when a skill is read
+* or pinned, so one name can stand for a family of tools whose real names are
+* only known at runtime. The model sees a skill tool only after it reads, with
+* `read_file`, a skill that lists it, or the skill is pinned, and only while
+* that read or pin stays in the conversation it is sent; compaction that drops
+* the read or pin withdraws the tool.
+* Until then, calling the tool fails with the standard invalid-tool error and
+* the tool doesn't run. This controls what is in the model's context; it is
+* not a security boundary, since the model can read any `SKILL.md` at any
+* time.
+*
+* `include_tools` can also name a tool passed to the agent rather than to this
+* middleware. That tool wins over a skill tool of the same name. If it is
+* deferred (`extras: { defer_loading: true }`), reading or pinning the skill
+* discloses it early, and it stays deferred and searchable; if it is bound,
+* nothing changes.
+*
+*
 * @param options - Configuration options
 * @returns AgentMiddleware for skills loading and injection
+* @throws {ConfigurationError} If `tools` is neither an array nor a
+*   function (`SKILL_TOOLS_UNSUPPORTED_TYPE`), an entry isn't a client tool
+*   (`SKILL_TOOLS_UNSUPPORTED_TYPE`), or two entries share a name
+*   (`SKILL_TOOLS_DUPLICATE_NAME`).
 *
 * @example
 * ```typescript
@@ -5550,30 +6174,60 @@ function validateModulePath(raw) {
 */
 function createSkillsMiddleware(options) {
 	const { backend, sources } = options;
+	const skillToolResolver = toSkillToolResolver(options.tools);
+	const hasSkillTools = typeof options.tools === "function" || Array.isArray(options.tools) && options.tools.length > 0;
 	return createMiddleware({
 		name: "SkillsMiddleware",
 		stateSchema: SkillsStateSchema,
 		async beforeModel(state) {
-			if (state.skillsMetadata !== null && state.skillsMetadata !== void 0) return;
+			const needsLoad = state.skillsMetadata === null || state.skillsMetadata === void 0;
+			const pinnedNames = state.pinnedSkills ?? [];
+			if (!needsLoad && pinnedNames.length === 0) return;
 			const resolvedBackend = await resolveBackend(backend, { state });
-			const allSkills = /* @__PURE__ */ new Map();
-			for (const sourcePath of sources) try {
-				const skills = await listSkillsFromBackend(resolvedBackend, sourcePath);
-				for (const skill of skills) allSkills.set(skill.name, skill);
-			} catch (error) {
-				console.debug(`[BackendSkillsMiddleware] Failed to load skills from ${sourcePath}:`, error);
-			}
-			return { skillsMetadata: Array.from(allSkills.values()) };
+			const skillsMetadata = state.skillsMetadata ?? await loadSkills(resolvedBackend, sources);
+			if (pinnedNames.length === 0) return { skillsMetadata };
+			const messages = await buildPinnedSkillMessages(resolvedBackend, pinnedNames, skillsMetadata);
+			return {
+				...needsLoad && { skillsMetadata },
+				...messages.length > 0 && { messages },
+				pinnedSkills: new Overwrite([])
+			};
 		},
-		wrapModelCall(request, handler) {
+		async wrapModelCall(request, handler) {
 			const skillsMetadata = request.state?.skillsMetadata || [];
 			const skillsLocations = formatSkillsLocations(sources);
 			const skillsList = formatSkillsList(skillsMetadata, sources);
 			const skillsSection = SKILLS_SYSTEM_PROMPT.replace("{skills_locations}", skillsLocations).replace("{skills_list}", skillsList);
 			const newSystemMessage = request.systemMessage.concat(skillsSection);
-			return handler({
+			const prompted = {
 				...request,
 				systemMessage: newSystemMessage
+			};
+			const reads = findSkillReads(request.messages, skillsMetadata);
+			const { request: disclosed, record } = reads.length === 0 ? {
+				request: prompted,
+				record: {}
+			} : await discloseSkillTools(prompted, reads, skillToolResolver);
+			const response = await handler(disclosed);
+			const stored = request.state._skillToolsDisclosed;
+			if (!hasSkillTools && Object.keys(stored ?? {}).length === 0) return response;
+			if (typeof response === "object" && response !== null && "structuredResponse" in response) return response;
+			return new Command({ update: { _skillToolsDisclosed: record } });
+		},
+		async wrapToolCall(request, handler) {
+			if (request.tool !== void 0) return handler(request);
+			const name = request.toolCall.name;
+			const record = request.state._skillToolsDisclosed ?? {};
+			const includeName = Object.hasOwn(record, name) ? record[name] : void 0;
+			if (includeName === void 0) return handler(request);
+			const tool = (await callSkillToolResolver(skillToolResolver, includeName, request.runtime)).find((candidate) => candidate.name === name);
+			if (tool === void 0) {
+				console.warn(`Skill tool '${name}' was disclosed via '${includeName}', but the resolver no longer returns it`);
+				return handler(request);
+			}
+			return handler({
+				...request,
+				tool
 			});
 		}
 	});
@@ -6343,46 +6997,6 @@ function createAsyncSubAgentMiddleware(options) {
 	});
 }
 //#endregion
-//#region src/errors.ts
-const CONFIGURATION_ERROR_SYMBOL = Symbol.for("deepagents.configuration_error");
-/**
-* Thrown when `createDeepAgent` receives invalid configuration.
-*
-* Follows the same pattern as {@link SandboxError}: a human-readable
-* `message`, a structured `code` for programmatic handling, and a
-* static `isInstance` guard that works across realms.
-*
-* @example
-* ```typescript
-* try {
-*   createDeepAgent({ tools: [myTool] });
-* } catch (error) {
-*   if (ConfigurationError.isInstance(error)) {
-*     switch (error.code) {
-*       case "TOOL_NAME_COLLISION":
-*         console.error("Rename your tool:", error.message);
-*         break;
-*     }
-*   }
-* }
-* ```
-*/
-var ConfigurationError = class ConfigurationError extends Error {
-	code;
-	cause;
-	[CONFIGURATION_ERROR_SYMBOL] = true;
-	name = "ConfigurationError";
-	constructor(message, code, cause) {
-		super(message);
-		this.code = code;
-		this.cause = cause;
-		Object.setPrototypeOf(this, ConfigurationError.prototype);
-	}
-	static isInstance(error) {
-		return typeof error === "object" && error !== null && error[CONFIGURATION_ERROR_SYMBOL] === true;
-	}
-};
-//#endregion
 //#region src/middleware/cache.ts
 /**
 * Creates a middleware that places a cache breakpoint at the end of the static
@@ -7248,13 +7862,10 @@ function createDeepAgent(params = {}) {
 		harnessProfile.systemPromptSuffix
 	]);
 	/**
-	* Process subagents to add SkillsMiddleware for those with their own skills.
-	*
-	* Custom subagents do NOT inherit skills from the main agent by default.
-	* Only the general-purpose subagent inherits the main agent's skills.
-	* If a custom subagent needs skills, it must specify its own `skills` array.
+	* Build the default head of a declarative subagent's middleware stack.
+	* Skills go in the tail instead (see buildSubagentMiddleware).
 	*/
-	const createSubagentDefaultMiddleware = (input, subagentProfile, forked) => {
+	const createSubagentDefaultMiddleware = (input, subagentProfile) => {
 		const effectivePermissions = input.permissions ?? permissions;
 		return [
 			createFilesystemMiddleware({
@@ -7263,23 +7874,33 @@ function createDeepAgent(params = {}) {
 				tools: computeProfileFilesystemTools(subagentProfile)
 			}),
 			createSummarizationMiddleware({ backend }),
-			createPatchToolCallsMiddleware(),
-			...!forked && input.skills != null && input.skills.length > 0 ? [createSkillsMiddleware({
-				backend,
-				sources: input.skills
-			})] : []
+			createPatchToolCallsMiddleware()
 		];
 	};
-	const buildSubagentMiddleware = (input) => {
+	/**
+	* The skills middleware for a stack: the last `SkillsMiddleware` among its
+	* custom middleware, else one built from `sources`, else none. A custom one
+	* is picked here rather than left to replace the default by name, because
+	* without `sources` there is no default to replace and it would run with
+	* the novel middleware instead.
+	*/
+	const resolveSkillsMiddleware = (sources, custom) => {
+		const passed = custom.findLast((entry) => entry.name === "SkillsMiddleware");
+		if (passed !== void 0) return [passed];
+		return sources != null && sources.length > 0 ? [createSkillsMiddleware({
+			backend,
+			sources
+		})] : [];
+	};
+	const buildSubagentMiddleware = (input, generalPurpose = false) => {
 		const subagentProfile = resolveSubagentProfile(input.model);
 		const forked = isForkedSubAgent(input);
-		const subagentDefaultMiddleware = createSubagentDefaultMiddleware(input, subagentProfile, forked);
-		if (forked && skills != null && skills.length > 0) subagentDefaultMiddleware.unshift(createSkillsMiddleware({
-			backend,
-			sources: skills
-		}));
-		let subagentMiddleware = mergeMiddlewareStack(subagentDefaultMiddleware, forked && customMiddleware.length > 0 ? mergeMiddleware$1(customMiddleware, input.middleware ?? []) : input.middleware ?? [], [
+		const subagentDefaultMiddleware = createSubagentDefaultMiddleware(input, subagentProfile);
+		const inputMiddleware = forked && customMiddleware.length > 0 ? mergeMiddleware$1(customMiddleware, input.middleware ?? []) : input.middleware ?? [];
+		const subagentSkillsMiddleware = generalPurpose ? resolveSkillsMiddleware(skills, customMiddleware) : resolveSkillsMiddleware(forked ? skills : input.skills, inputMiddleware);
+		let subagentMiddleware = mergeMiddlewareStack(subagentDefaultMiddleware, inputMiddleware, [
 			...resolveMiddleware(subagentProfile.extraMiddleware),
+			...subagentSkillsMiddleware,
 			...cacheMiddleware,
 			...forked && memory != null && memory.length > 0 ? [createMemoryMiddleware({
 				backend,
@@ -7292,9 +7913,9 @@ function createDeepAgent(params = {}) {
 		if (!subagentProfile.excludedMiddleware.has("UnsupportedContentMiddleware") && !subagentMiddleware.some((middleware) => middleware.name === "UnsupportedContentMiddleware")) subagentMiddleware.push(createUnsupportedContentMiddleware());
 		return subagentMiddleware;
 	};
-	const normalizeSubagentSpec = (input) => ({
+	const normalizeSubagentSpec = (input, generalPurpose = false) => ({
 		...input,
-		middleware: buildSubagentMiddleware(input)
+		middleware: buildSubagentMiddleware(input, generalPurpose)
 	});
 	const allSubagents = subagents;
 	const asyncSubAgents = allSubagents.filter((item) => isAsyncSubAgent(item));
@@ -7307,16 +7928,12 @@ function createDeepAgent(params = {}) {
 			description: gpConfig?.description ?? GENERAL_PURPOSE_SUBAGENT.description,
 			systemPrompt: gpSystemPrompt,
 			model,
-			skills,
 			tools: effectiveTools
-		});
+		}, true);
 		generalPurposeSpec.middleware = mergeMiddlewareStack(generalPurposeSpec.middleware ?? [], customMiddleware, [], { appendNew: false });
 		inlineSubagents.unshift(generalPurposeSpec);
 	}
-	const skillsMiddleware = skills != null && skills.length > 0 ? [createSkillsMiddleware({
-		backend,
-		sources: skills
-	})] : [];
+	const skillsMiddleware = resolveSkillsMiddleware(skills, customMiddleware);
 	const [fsMiddleware, subagentMiddleware, summarizationMiddleware, patchToolCallsMiddleware] = [
 		createFilesystemMiddleware({
 			backend,
@@ -7335,7 +7952,6 @@ function createDeepAgent(params = {}) {
 		createPatchToolCallsMiddleware()
 	];
 	let middleware = mergeMiddlewareStack([
-		...skillsMiddleware,
 		fsMiddleware,
 		subagentMiddleware,
 		summarizationMiddleware,
@@ -7343,6 +7959,7 @@ function createDeepAgent(params = {}) {
 		...asyncSubAgents.length > 0 ? [createAsyncSubAgentMiddleware({ asyncSubAgents })] : []
 	], customMiddleware, [
 		...resolveMiddleware(harnessProfile.extraMiddleware),
+		...skillsMiddleware,
 		...cacheMiddleware,
 		...memoryMiddleware,
 		...interruptOn ? [humanInTheLoopMiddleware({ interruptOn })] : []
@@ -9470,6 +10087,6 @@ var LangSmithSandbox = class LangSmithSandbox extends BaseSandbox {
 	}
 };
 //#endregion
-export { checkEmptyContent as $, createPatchToolCallsMiddleware as A, CompositeBackend as B, MAX_SKILL_DESCRIPTION_LENGTH as C, skillsMetadataValue as D, createSkillsMiddleware as E, createSubAgent as F, StateBackend as G, createUnsupportedContentMiddleware as H, createSubAgentMiddleware as I, isSandboxBackend as J, SandboxError as K, computeSummarizationDefaults as L, DEFAULT_SUBAGENT_PROMPT as M, GENERAL_PURPOSE_SUBAGENT as N, createMemoryMiddleware as O, SUBAGENT_RESPONSE_FORMAT_CONFIG_KEY as P, adaptSandboxProtocol as Q, createSummarizationMiddleware as R, createCompletionCallbackMiddleware as S, MAX_SKILL_NAME_LENGTH as T, multimodalBlockSupported as U, MULTIMODAL_BLOCK_TYPES as V, scrubUnsupportedMultimodalContent as W, resolveBackend as X, isSandboxProtocol as Y, adaptBackendProtocol as Z, createHarnessProfile as _, ASYNC_TASK_SYSTEM_PROMPT as a, createAsyncSubAgentMiddleware as b, TASK_SYSTEM_PROMPT as c, registerHarnessProfile as d, getMimeType as et, generalPurposeSubagentConfigSchema as f, EMPTY_HARNESS_PROFILE as g, serializeProfile as h, StoreBackend as i, DEFAULT_GENERAL_PURPOSE_DESCRIPTION as j, filesValue as k, createDeepAgent as l, parseHarnessProfileConfig as m, BaseSandbox as n, normalizeReadPagination as nt, BASE_AGENT_PROMPT as o, harnessProfileConfigSchema as p, applyGrepMaxCount as q, ContextHubBackend as r, performStringReplacement as rt, EXECUTION_SYSTEM_PROMPT as s, LangSmithSandbox as t, isTextMimeType as tt, getHarnessProfile as u, REQUIRED_MIDDLEWARE_NAMES as v, MAX_SKILL_FILE_SIZE as w, isAsyncSubAgent as x, ConfigurationError as y, createFilesystemMiddleware as z };
+export { adaptSandboxProtocol as $, filesValue as A, createFilesystemMiddleware as B, MAX_SKILL_FILE_SIZE as C, skillsMetadataValue as D, pinnedSkillsValue as E, SUBAGENT_RESPONSE_FORMAT_CONFIG_KEY as F, scrubUnsupportedMultimodalContent as G, MULTIMODAL_BLOCK_TYPES as H, createSubAgent as I, applyGrepMaxCount as J, StateBackend as K, createSubAgentMiddleware as L, DEFAULT_GENERAL_PURPOSE_DESCRIPTION as M, DEFAULT_SUBAGENT_PROMPT as N, ConfigurationError as O, GENERAL_PURPOSE_SUBAGENT as P, adaptBackendProtocol as Q, computeSummarizationDefaults as R, MAX_SKILL_DESCRIPTION_LENGTH as S, createSkillsMiddleware as T, createUnsupportedContentMiddleware as U, CompositeBackend as V, multimodalBlockSupported as W, isSandboxProtocol as X, isSandboxBackend as Y, resolveBackend as Z, createHarnessProfile as _, ASYNC_TASK_SYSTEM_PROMPT as a, setRealpath as at, isAsyncSubAgent as b, TASK_SYSTEM_PROMPT as c, registerHarnessProfile as d, checkEmptyContent as et, generalPurposeSubagentConfigSchema as f, EMPTY_HARNESS_PROFILE as g, serializeProfile as h, StoreBackend as i, performStringReplacement as it, createPatchToolCallsMiddleware as j, createMemoryMiddleware as k, createDeepAgent as l, parseHarnessProfileConfig as m, BaseSandbox as n, isTextMimeType as nt, BASE_AGENT_PROMPT as o, harnessProfileConfigSchema as p, SandboxError as q, ContextHubBackend as r, normalizeReadPagination as rt, EXECUTION_SYSTEM_PROMPT as s, LangSmithSandbox as t, getMimeType as tt, getHarnessProfile as u, REQUIRED_MIDDLEWARE_NAMES as v, MAX_SKILL_NAME_LENGTH as w, createCompletionCallbackMiddleware as x, createAsyncSubAgentMiddleware as y, createSummarizationMiddleware as z };
 
-//# sourceMappingURL=langsmith--RbtjNdQ.js.map
+//# sourceMappingURL=langsmith-v_uskil7.js.map