deepagents 1.14.2 → 1.15.0

package/dist/{langsmith-CjOWZAS2.cjs → langsmith-DMOexB11.cjs}

@@ -33,9 +33,30 @@ zod = __toESM(zod, 1);
 let langchain_chat_models_universal = require("langchain/chat_models/universal");
 let yaml = require("yaml");
 yaml = __toESM(yaml, 1);
+let _langchain_core_runnables = require("@langchain/core/runnables");
+let _langchain_core_tools = require("@langchain/core/tools");
+let _langchain_core_language_models_base = require("@langchain/core/language_models/base");
+let _langchain_core_utils_function_calling = require("@langchain/core/utils/function_calling");
+let _langchain_core_utils_json_schema = require("@langchain/core/utils/json_schema");
+let _langchain_core_utils_types = require("@langchain/core/utils/types");
 let _langchain_langgraph_sdk = require("@langchain/langgraph-sdk");
 let langsmith = require("langsmith");
 let langsmith_experimental_sandbox = require("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.
@@ -667,6 +688,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),
@@ -1603,11 +1626,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("/")}`;
@@ -1657,14 +1682,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);
 	}
@@ -1677,11 +1703,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
@@ -2448,25 +2492,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
@@ -2639,27 +2700,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 = langchain.context`
   Lists all files in a directory.
@@ -2747,13 +2837,13 @@ function getExecuteToolDescription(hasGrep, hasGlob) {
 function createLsTool(backend, options) {
 	const { customDescription, permissions } = options;
 	return (0, langchain.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)`);
@@ -2776,23 +2866,17 @@ function createLsTool(backend, options) {
 function createReadFileTool(backend, options) {
 	const { customDescription, toolTokenLimitBeforeEvict, permissions } = options;
 	return (0, langchain.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");
@@ -2801,10 +2885,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,
@@ -2870,11 +2951,11 @@ function createReadFileTool(backend, options) {
 function createWriteFileTool(backend, options) {
 	const { customDescription, permissions } = options;
 	return (0, langchain.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 langchain.ToolMessage({
 			content: `Successfully wrote to '${file_path}'`,
@@ -2902,11 +2983,11 @@ function createWriteFileTool(backend, options) {
 function createEditFileTool(backend, options) {
 	const { customDescription, permissions } = options;
 	return (0, langchain.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 langchain.ToolMessage({
 			content: `Successfully replaced ${result.occurrences} occurrence(s) in '${file_path}'`,
@@ -2946,6 +3027,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);
@@ -2972,13 +3064,13 @@ function createDeleteTool(backend, options) {
 function createGlobTool(backend, options) {
 	const { customDescription, permissions } = options;
 	return (0, langchain.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");
@@ -2998,14 +3090,14 @@ function createGlobTool(backend, options) {
 function createGrepTool(backend, options) {
 	const { customDescription, permissions, includeExecution, grepMaxCount } = options;
 	return (0, langchain.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");
@@ -4197,10 +4289,12 @@ const EXCLUDED_STATE_KEYS = [
 	"todos",
 	"structuredResponse",
 	"skillsMetadata",
+	"pinnedSkills",
 	"memoryContents",
 	...CALL_COUNT_STATE_KEYS,
 	"_summarizationEvent",
 	"_summarizationSessionId",
+	"_skillToolsDisclosed",
 	FORKED_CONTEXT_KEY
 ];
 /**
@@ -4219,9 +4313,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.
@@ -4664,7 +4760,8 @@ function patchDanglingToolCalls(messages) {
 				patchedMessages.push(new langchain.ToolMessage({
 					content: toolMsg,
 					name: toolCall.name,
-					tool_call_id: toolCall.id
+					tool_call_id: toolCall.id,
+					status: "error"
 				}));
 			}
 		}
@@ -5106,6 +5203,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.
@@ -5165,6 +5302,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.
 */
@@ -5206,11 +5347,52 @@ const SkillMetadataEntrySchema = zod.z.object({
 */
 const skillsMetadataValue = zod.z.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 _langchain_langgraph.ReducedValue(zod.z.array(zod.z.string()).default(() => []), { reducer: (stored, written) => [...stored ?? [], ...written ?? []] });
+/**
 * State schema for skills middleware.
 */
 const SkillsStateSchema = new _langchain_langgraph.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 _langchain_langgraph.ReducedValue(zod.z.record(zod.z.string(), zod.z.string()).optional(), { reducer: (_previous, next) => next })
 });
 /**
 * Skills System Documentation prompt template.
@@ -5312,7 +5494,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).
@@ -5323,6 +5506,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;
@@ -5360,7 +5545,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;
@@ -5479,6 +5664,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 _langchain_core_messages.HumanMessage({
+		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).
 */
@@ -5538,6 +5778,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 _langchain_core_runnables.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 (!_langchain_core_messages.AIMessage.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 (_langchain_core_messages.ToolMessage.isInstance(message) && message.status !== "error") path = readPaths.get(message.tool_call_id);
+		else if (_langchain_core_messages.HumanMessage.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 ((0, _langchain_core_language_models_base.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) && (0, _langchain_core_tools.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 = _langchain_core_messages.AIMessage.isInstance(message) && message.content.length === 0 && !message.tool_calls?.length;
+			if (!_langchain_core_messages.ToolMessage.isInstance(message) && !_langchain_core_messages.HumanMessage.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 _langchain_core_messages.SystemMessage({ 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 _langchain_core_runnables.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: (0, _langchain_core_utils_types.isInteropZodSchema)(tool.schema) ? (0, _langchain_core_utils_json_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",
+			...(0, _langchain_core_utils_function_calling.convertToOpenAIFunction)(tool)
+		}]
+	};
+}
 /**
 * Create backend-agnostic middleware for loading and exposing agent skills.
 *
@@ -5561,8 +6131,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
@@ -5574,30 +6198,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 (0, langchain.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 _langchain_langgraph.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 _langchain_langgraph.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
 			});
 		}
 	});
@@ -6367,46 +7021,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
@@ -7272,13 +7886,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({
@@ -7287,23 +7898,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,
@@ -7316,9 +7937,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));
@@ -7331,16 +7952,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,
@@ -7359,7 +7976,6 @@ function createDeepAgent(params = {}) {
 		createPatchToolCallsMiddleware()
 	];
 	let middleware = mergeMiddlewareStack([
-		...skillsMiddleware,
 		fsMiddleware,
 		subagentMiddleware,
 		summarizationMiddleware,
@@ -7367,6 +7983,7 @@ function createDeepAgent(params = {}) {
 		...asyncSubAgents.length > 0 ? [createAsyncSubAgentMiddleware({ asyncSubAgents })] : []
 	], customMiddleware, [
 		...resolveMiddleware(harnessProfile.extraMiddleware),
+		...skillsMiddleware,
 		...cacheMiddleware,
 		...memoryMiddleware,
 		...interruptOn ? [(0, langchain.humanInTheLoopMiddleware)({ interruptOn })] : []
@@ -9812,6 +10429,12 @@ Object.defineProperty(exports, "performStringReplacement", {
 		return performStringReplacement;
 	}
 });
+Object.defineProperty(exports, "pinnedSkillsValue", {
+	enumerable: true,
+	get: function() {
+		return pinnedSkillsValue;
+	}
+});
 Object.defineProperty(exports, "registerHarnessProfile", {
 	enumerable: true,
 	get: function() {
@@ -9836,6 +10459,12 @@ Object.defineProperty(exports, "serializeProfile", {
 		return serializeProfile;
 	}
 });
+Object.defineProperty(exports, "setRealpath", {
+	enumerable: true,
+	get: function() {
+		return setRealpath;
+	}
+});
 Object.defineProperty(exports, "skillsMetadataValue", {
 	enumerable: true,
 	get: function() {
@@ -9843,4 +10472,4 @@ Object.defineProperty(exports, "skillsMetadataValue", {
 	}
 });
 
-//# sourceMappingURL=langsmith-CjOWZAS2.cjs.map
+//# sourceMappingURL=langsmith-DMOexB11.cjs.map