@kiturone/kapibala 0.0.4 → 0.0.5

package/dist/index.js

@@ -1523,10 +1523,577 @@ var UnicodeTokenEstimator = class {
 };
 
 // src/context/manager.ts
+import { createHash as createHash6 } from "crypto";
+
+// src/capabilities/skills/frontmatter.ts
+import path4 from "path";
+
+// src/capabilities/skills/types.ts
+var SKILL_LIMITS = Object.freeze({
+  fileBytes: 128 * 1024,
+  frontmatterBytes: 16 * 1024,
+  depth: 6,
+  directories: 2e3,
+  entries: 2e4,
+  descriptionChars: 250,
+  catalogTokens: 2e3,
+  queryTokens: 1e3,
+  resourceBytes: 64 * 1024,
+  resourceFiles: 20
+});
+
+// src/capabilities/skills/frontmatter.ts
+function isSkillName(value) {
+  return value.length <= 64 && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
+}
+function fail(message) {
+  throw new Error(`Invalid skill frontmatter: ${message}`);
+}
+function uncomment(value) {
+  let quote = "";
+  let bracket = false;
+  let previous = "";
+  for (let i = 0; i < value.length; i++) {
+    const char = value[i];
+    if (quote === '"' && char === "\\") {
+      i++;
+      continue;
+    }
+    if (quote === "'" && char === "'" && value[i + 1] === "'") {
+      i++;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) quote = "";
+      continue;
+    }
+    if (/\s/.test(char)) continue;
+    if ((char === "'" || char === '"') && (previous === "" || bracket && (previous === "[" || previous === ","))) {
+      quote = char;
+    } else if (char === "[") bracket = true;
+    else if (char === "]") bracket = false;
+    else if (char === "#" && (previous === "" || /\s/.test(value[i - 1])))
+      return value.slice(0, i).trimEnd();
+    previous = char;
+  }
+  if (quote) fail("unterminated quote");
+  return value.trimEnd();
+}
+function scalar(raw) {
+  const value = uncomment(raw.trim());
+  if (!value) return "";
+  if (value.startsWith('"')) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      fail("invalid double-quoted string");
+    }
+  }
+  if (value.startsWith("'")) {
+    if (!/^'(?:[^']|'')*'$/.test(value)) fail("invalid single-quoted string");
+    return value.slice(1, -1).replace(/''/g, "'");
+  }
+  if (value.startsWith("[")) {
+    if (!value.endsWith("]")) fail("unterminated list");
+    const inner = value.slice(1, -1);
+    if (!inner.trim()) return [];
+    const parts = [];
+    let quote = "";
+    let start = 0;
+    for (let i = 0; i < inner.length; i++) {
+      const char = inner[i];
+      if (quote === '"' && char === "\\") {
+        i++;
+        continue;
+      }
+      if (quote === "'" && char === "'" && inner[i + 1] === "'") {
+        i++;
+        continue;
+      }
+      if (quote) {
+        if (char === quote) quote = "";
+      } else if (char === "'" || char === '"') quote = char;
+      else if (char === ",") {
+        parts.push(inner.slice(start, i));
+        start = i + 1;
+      }
+    }
+    if (quote) fail("unterminated list quote");
+    parts.push(inner.slice(start));
+    const items = parts.map((part) => scalar(part));
+    if (items.some((item) => typeof item !== "string")) fail("list values must be strings");
+    return items;
+  }
+  if (/^[!&*{}]|^<<:/.test(value)) fail("unsupported YAML structure");
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (value === "null" || value === "~") return null;
+  if (/^-?\d+(?:\.\d+)?$/.test(value)) return Number(value);
+  return value;
+}
+function blockScalar(lines, indicator) {
+  const nonempty2 = lines.filter((line) => line.trim());
+  const indent = nonempty2.length ? Math.min(...nonempty2.map((line) => line.match(/^ */)[0].length)) : 0;
+  if (nonempty2.some((line) => line.match(/^ */)[0].length === 0))
+    fail("block scalar must be indented");
+  const values = lines.map((line) => line.trim() ? line.slice(indent) : "");
+  let text = "";
+  if (indicator.startsWith("|")) {
+    text = values.join("\n") + (values.length ? "\n" : "");
+  } else {
+    const moreIndented = (line) => line.startsWith(" ");
+    let blanks = 0;
+    let previous;
+    for (const value of values) {
+      if (!value) {
+        blanks++;
+        continue;
+      }
+      if (previous === void 0) text += "\n".repeat(blanks);
+      else if (!blanks) text += moreIndented(previous) || moreIndented(value) ? "\n" : " ";
+      else
+        text += "\n".repeat(blanks) + (moreIndented(previous) || moreIndented(value) ? "\n" : "");
+      blanks = 0;
+      text += value;
+      previous = value;
+    }
+    text += "\n".repeat(blanks);
+    if (values.length) text += "\n";
+  }
+  if (indicator.endsWith("-")) return text.replace(/\n+$/, "");
+  if (indicator.endsWith("+")) return text;
+  return text.replace(/\n+$/, "") + (text ? "\n" : "");
+}
+function parseSkillDocument(content, filePath) {
+  if (Buffer.byteLength(content, "utf8") > SKILL_LIMITS.fileBytes) fail("file exceeds 128 KiB");
+  const raw = content.replace(/^\uFEFF/, "");
+  const opening = /^---[ \t]*\r?\n/.exec(raw);
+  if (!opening) fail("missing opening delimiter");
+  const rest = raw.slice(opening[0].length);
+  const closing = /^---[ \t]*(?:\r?\n|$)/m.exec(rest);
+  if (!closing) fail("missing closing delimiter");
+  const header = rest.slice(0, closing.index);
+  if (Buffer.byteLength(header, "utf8") > SKILL_LIMITS.frontmatterBytes)
+    fail("header exceeds 16 KiB");
+  const body = rest.slice(closing.index + closing[0].length).replace(/\r\n/g, "\n");
+  const lines = header.replace(/\r\n/g, "\n").split("\n");
+  const values = /* @__PURE__ */ Object.create(null);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim() || line.trimStart().startsWith("#")) continue;
+    const match = /^([a-zA-Z0-9_-]+):(?:[ \t]*(.*))?$/.exec(line);
+    if (!match) fail("invalid top-level mapping");
+    const key = match[1];
+    if (Object.hasOwn(values, key)) fail("duplicate key");
+    const value = uncomment(match[2] ?? "").trim();
+    if (/^[|>][+-]?$/.test(value)) {
+      const block = [];
+      while (i + 1 < lines.length && (!lines[i + 1].trim() || /^ +/.test(lines[i + 1]))) {
+        block.push(lines[++i]);
+      }
+      if (i === lines.length - 1 && block.at(-1) === "") block.pop();
+      values[key] = blockScalar(block, value);
+    } else if (!value && /^ +\S/.test(lines[i + 1] ?? "")) {
+      const nested = [];
+      while (i + 1 < lines.length && (!lines[i + 1].trim() || /^ +/.test(lines[i + 1])))
+        nested.push(lines[++i]);
+      const significant = nested.filter((item) => item.trim() && !item.trimStart().startsWith("#"));
+      if (significant.every((item) => /^ +- /.test(item))) {
+        values[key] = significant.map((item) => scalar(item.trimStart().slice(2)));
+        if (values[key].some((item) => typeof item !== "string"))
+          fail("list values must be strings");
+      } else {
+        const mapping = /* @__PURE__ */ Object.create(null);
+        const indent = significant[0]?.match(/^ */)[0].length;
+        for (const item of significant) {
+          if (item.match(/^ */)[0].length !== indent) fail("nested mappings are unsupported");
+          const pair = /^ +([a-zA-Z0-9_-]+):\s*(.*)$/.exec(item);
+          if (!pair || Object.hasOwn(mapping, pair[1])) fail("invalid or duplicate nested key");
+          mapping[pair[1]] = scalar(pair[2]);
+        }
+        values[key] = mapping;
+      }
+    } else values[key] = scalar(value);
+  }
+  const diagnostics = [];
+  const warn = (code, message) => diagnostics.push({ code, level: "warn", path: filePath, message });
+  const directoryName = path4.basename(path4.dirname(filePath));
+  const name = values.name === void 0 ? directoryName : values.name;
+  if (typeof name !== "string" || !isSkillName(name)) fail("invalid name");
+  if (values.name === void 0) warn("SKILL_NAME_FALLBACK", "\u540D\u79F0\u7F3A\u7701\uFF0C\u4F7F\u7528\u76EE\u5F55\u540D");
+  else if (name !== directoryName) warn("SKILL_NAME_MISMATCH", "\u540D\u79F0\u4E0E\u76EE\u5F55\u540D\u4E0D\u540C");
+  const description = values.description;
+  if (typeof description !== "string" || !description.trim())
+    fail("description must be a nonempty string");
+  if (Array.from(description).length > 1024)
+    warn("SKILL_DESCRIPTION_LONG", "\u63CF\u8FF0\u8D85\u8FC7\u89C4\u8303\u957F\u5EA6\uFF0C\u76EE\u5F55\u5C55\u793A\u5C06\u7F29\u77ED");
+  for (const key of ["disable-model-invocation", "user-invocable"]) {
+    if (values[key] !== void 0 && typeof values[key] !== "boolean")
+      fail("invocation flag must be boolean");
+  }
+  const optional = (key) => {
+    const value = values[key];
+    if (value === void 0) return void 0;
+    if (typeof value !== "string") fail(`${key} must be a string`);
+    return value;
+  };
+  const compatibility = optional("compatibility");
+  if (compatibility && Array.from(compatibility).length > 500)
+    warn("SKILL_COMPATIBILITY_LONG", "\u517C\u5BB9\u8BF4\u660E\u8D85\u8FC7\u89C4\u8303\u957F\u5EA6");
+  let allowedTools;
+  if (values["allowed-tools"] !== void 0) {
+    const allowed = values["allowed-tools"];
+    allowedTools = typeof allowed === "string" ? allowed.split(/\s+/).filter(Boolean) : Array.isArray(allowed) && allowed.every((item) => typeof item === "string") ? [...allowed] : fail("allowed-tools must be string or string list");
+    warn("SKILL_PERMISSION_SEMANTICS", "\u5DE5\u5177\u58F0\u660E\u4EC5\u6536\u7D27\u6743\u9650\uFF0C\u4E0D\u65B0\u589E\u9884\u6279\u51C6\u6388\u6743");
+  }
+  let metadata;
+  if (values.metadata !== void 0) {
+    if (!values.metadata || typeof values.metadata !== "object" || Array.isArray(values.metadata) || Object.values(values.metadata).some((item) => typeof item !== "string"))
+      fail("metadata must map strings to strings");
+    metadata = values.metadata;
+  }
+  const known = /* @__PURE__ */ new Set([
+    "name",
+    "description",
+    "license",
+    "compatibility",
+    "metadata",
+    "allowed-tools",
+    "when",
+    "when_to_use",
+    "disable-model-invocation",
+    "user-invocable",
+    "argument-hint"
+  ]);
+  const unsupported = /* @__PURE__ */ new Set(["context", "hooks", "model", "agent", "shell"]);
+  const blocked = Object.keys(values).filter((key) => unsupported.has(key));
+  if (/!\x60[^\x60]+\x60|^\s*\x60{3}!/m.test(body)) blocked.push("dynamic-shell");
+  for (const key of Object.keys(values)) {
+    if (!known.has(key) && !unsupported.has(key))
+      warn("SKILL_UNKNOWN_FIELD", `\u672A\u89E3\u91CA\u5143\u6570\u636E\u5B57\u6BB5\uFF1A${key}`);
+  }
+  const unavailableReason = blocked.length ? `\u4E0D\u652F\u6301\u7684\u6267\u884C\u6269\u5C55\uFF1A${blocked.join(", ")}` : void 0;
+  if (unavailableReason) warn("SKILL_UNSUPPORTED", unavailableReason);
+  return {
+    name,
+    description,
+    body,
+    frontmatter: values,
+    metadata,
+    allowedTools,
+    license: optional("license"),
+    compatibility,
+    when: optional("when") ?? optional("when_to_use"),
+    argumentHint: optional("argument-hint"),
+    modelInvocable: values["disable-model-invocation"] !== true,
+    userInvocable: values["user-invocable"] !== false,
+    available: !unavailableReason,
+    unavailableReason,
+    diagnostics
+  };
+}
+
+// src/capabilities/skills/scanner.ts
 import { createHash as createHash5 } from "crypto";
+import fs5 from "fs/promises";
+import path5 from "path";
+function skillFailure(code, message) {
+  const immediate = ["SKILL_NOT_COMMITTED", "SKILL_CURSOR_EXPIRED"].includes(code);
+  const userAction = [
+    "SKILL_CHANGED",
+    "SKILL_UNTRUSTED",
+    "SKILL_BODY_BUDGET_EXCEEDED",
+    "SKILL_CONTEXT_LOST"
+  ].includes(code);
+  return new KapibalaError(message, {
+    code,
+    safeMessage: message,
+    retryPolicy: immediate ? "immediate" : userAction ? "after_user_action" : "never"
+  });
+}
+function isWithinSkillRoot(root, target) {
+  const relative = path5.relative(root, target);
+  return relative !== ".." && !relative.startsWith(`..${path5.sep}`) && !path5.isAbsolute(relative);
+}
+function skillPathKey(value) {
+  return process.platform === "win32" ? path5.resolve(value).toLowerCase() : path5.resolve(value);
+}
+function compareSkillPaths(left, right) {
+  const a = Array.from(left);
+  const b = Array.from(right);
+  for (let i = 0; i < Math.min(a.length, b.length); i++) {
+    const difference = a[i].codePointAt(0) - b[i].codePointAt(0);
+    if (difference) return difference;
+  }
+  return a.length - b.length;
+}
+async function readBoundedSkillText(filePath, maximum, signal) {
+  signal?.throwIfAborted();
+  const handle = await fs5.open(filePath, "r");
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size > maximum)
+      throw skillFailure("SKILL_INVALID_INPUT", "\u6587\u4EF6\u4E0D\u662F\u53EF\u8BFB\u53D6\u7684\u6709\u754C\u6587\u672C");
+    const chunks = [];
+    let size = 0;
+    let position = 0;
+    while (true) {
+      signal?.throwIfAborted();
+      const buffer = Buffer.alloc(Math.min(16 * 1024, maximum + 1 - size));
+      const result = await handle.read(buffer, 0, buffer.length, position);
+      if (!result.bytesRead) break;
+      position += result.bytesRead;
+      size += result.bytesRead;
+      if (size > maximum) throw skillFailure("SKILL_INVALID_INPUT", "\u6587\u4EF6\u8D85\u8FC7\u8BFB\u53D6\u4E0A\u9650");
+      chunks.push(buffer.subarray(0, result.bytesRead));
+    }
+    const bytes = Buffer.concat(chunks);
+    if (bytes.includes(0)) throw skillFailure("SKILL_INVALID_INPUT", "\u4E0D\u652F\u6301\u4E8C\u8FDB\u5236\u8D44\u6E90");
+    try {
+      return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    } catch {
+      throw skillFailure("SKILL_INVALID_INPUT", "\u6587\u4EF6\u4E0D\u662F\u6709\u6548 UTF-8 \u6587\u672C");
+    }
+  } finally {
+    await handle.close();
+  }
+}
+function skillDigest(content) {
+  return createHash5("sha256").update(content, "utf8").digest("hex");
+}
+function ignoreExpression(pattern) {
+  let regex = "";
+  for (let i = 0; i < pattern.length; i++) {
+    const char = pattern[i];
+    if (char === "*" && pattern[i + 1] === "*") {
+      i++;
+      if (pattern[i + 1] === "/") {
+        i++;
+        regex += "(?:.*/)?";
+      } else regex += ".*";
+    } else if (char === "*") regex += "[^/]*";
+    else if (char === "?") regex += "[^/]";
+    else regex += char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(regex);
+}
+async function scanSkillRoot(root, signal) {
+  const result = { skills: [], diagnostics: [] };
+  const diagnose = (code, target, message) => result.diagnostics.push({ code, path: target, level: "warn", message });
+  let realRoot;
+  let boundary;
+  try {
+    realRoot = await fs5.realpath(root.path);
+    boundary = root.boundary ? await fs5.realpath(root.boundary) : realRoot;
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      diagnose("SKILL_SCAN_FAILED", root.path, "\u65E0\u6CD5\u89E3\u6790\u6280\u80FD\u626B\u63CF\u6839");
+    return result;
+  }
+  if (!isWithinSkillRoot(boundary, realRoot)) {
+    diagnose("SKILL_PATH_DENIED", root.path, "\u6280\u80FD\u626B\u63CF\u6839\u4F4D\u4E8E\u6388\u6743\u8FB9\u754C\u5916");
+    return result;
+  }
+  const visited = /* @__PURE__ */ new Set();
+  let directories = 0;
+  let entries = 0;
+  const trusted = root.trusted ?? root.scope !== "project";
+  const priority = root.scope === "project" ? root.kind === "agents" ? 1 : 0 : root.scope === "global" ? root.kind === "agents" ? 3 : 2 : 4;
+  const walk = async (directory, depth, inherited) => {
+    signal?.throwIfAborted();
+    if (depth > SKILL_LIMITS.depth || directories >= SKILL_LIMITS.directories || entries >= SKILL_LIMITS.entries) {
+      diagnose("SKILL_SCAN_LIMIT", directory, "\u6280\u80FD\u626B\u63CF\u8FBE\u5230\u6DF1\u5EA6\u3001\u76EE\u5F55\u6216\u6761\u76EE\u4E0A\u9650");
+      return;
+    }
+    let physical;
+    try {
+      physical = await fs5.realpath(directory);
+    } catch {
+      diagnose("SKILL_SCAN_FAILED", directory, "\u76EE\u5F55\u4E0D\u5B58\u5728\u6216\u94FE\u63A5\u5DF2\u635F\u574F");
+      return;
+    }
+    if (!isWithinSkillRoot(boundary, physical)) {
+      diagnose("SKILL_PATH_DENIED", directory, "\u6280\u80FD\u94FE\u63A5\u4F4D\u4E8E\u6388\u6743\u8FB9\u754C\u5916");
+      return;
+    }
+    const identity = skillPathKey(physical);
+    if (visited.has(identity)) return;
+    visited.add(identity);
+    directories++;
+    const rules = [...inherited];
+    const ignoreFile = path5.join(physical, ".gitignore");
+    try {
+      const realIgnore = await fs5.realpath(ignoreFile);
+      if (!isWithinSkillRoot(boundary, realIgnore)) throw new Error("outside");
+      const text = await readBoundedSkillText(realIgnore, SKILL_LIMITS.frontmatterBytes, signal);
+      for (let line of text.split(/\r?\n/)) {
+        line = line.trim();
+        if (!line || line.startsWith("#")) continue;
+        const negated = line.startsWith("!");
+        if (negated) line = line.slice(1);
+        if (line.startsWith("\\#") || line.startsWith("\\!")) line = line.slice(1);
+        if (/[\[\]{}\\]/.test(line)) {
+          diagnose("SKILL_IGNORE_UNSUPPORTED", ignoreFile, "\u5FFD\u7565\u8868\u8FBE\u5F0F\u4E0D\u5728\u652F\u6301\u5B50\u96C6\u5185");
+          continue;
+        }
+        const anchored = line.startsWith("/");
+        if (anchored) line = line.slice(1);
+        const directoryOnly = line.endsWith("/");
+        if (directoryOnly) line = line.slice(0, -1);
+        if (!line) continue;
+        const compiled = ignoreExpression(line).source;
+        rules.push({
+          directory,
+          negated,
+          expression: new RegExp(
+            `${anchored || line.includes("/") ? "^" : "(?:^|/)"}${compiled}${directoryOnly ? "(?:/|$)" : "$"}`
+          )
+        });
+      }
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      if (error.code !== "ENOENT")
+        diagnose("SKILL_IGNORE_UNSUPPORTED", ignoreFile, "\u5FFD\u7565\u6587\u4EF6\u65E0\u6CD5\u5B89\u5168\u8BFB\u53D6");
+    }
+    const ignored = (target, isDirectory) => {
+      let excluded = false;
+      for (const rule of rules) {
+        const relative = path5.relative(rule.directory, target).split(path5.sep).join("/");
+        if (relative.startsWith("../")) continue;
+        if (rule.expression.test(relative) || isDirectory && rule.expression.test(`${relative}/`))
+          excluded = !rule.negated;
+      }
+      return excluded;
+    };
+    const lexicalFile = path5.join(directory, "SKILL.md");
+    try {
+      const stat = await fs5.lstat(lexicalFile);
+      if (stat.isFile() || stat.isSymbolicLink()) {
+        if (ignored(lexicalFile, false)) return;
+        const actualFile = await fs5.realpath(lexicalFile);
+        if (!isWithinSkillRoot(boundary, actualFile)) {
+          diagnose("SKILL_PATH_DENIED", lexicalFile, "\u6280\u80FD\u6587\u4EF6\u94FE\u63A5\u4F4D\u4E8E\u6388\u6743\u8FB9\u754C\u5916");
+          return;
+        }
+        const raw = await readBoundedSkillText(actualFile, SKILL_LIMITS.fileBytes, signal);
+        const document = parseSkillDocument(raw, actualFile);
+        result.diagnostics.push(...document.diagnostics);
+        if (!trusted) diagnose("SKILL_UNTRUSTED", lexicalFile, "\u9879\u76EE\u6280\u80FD\u5C1A\u672A\u83B7\u5F97\u5BBF\u4E3B\u4FE1\u4EFB");
+        const {
+          frontmatter: _frontmatter,
+          diagnostics: _diagnostics,
+          body: _body,
+          ...data
+        } = document;
+        result.skills.push({
+          ...data,
+          scope: root.scope,
+          sourceRoot: realRoot,
+          filePath: actualFile,
+          discoveryRoot: path5.resolve(root.path),
+          discoveryPath: path5.resolve(lexicalFile),
+          baseDir: path5.dirname(actualFile),
+          contentDigest: skillDigest(raw),
+          priority,
+          disabled: false,
+          available: document.available && trusted,
+          unavailableReason: !trusted ? "\u9879\u76EE\u6280\u80FD\u5C1A\u672A\u4FE1\u4EFB" : document.unavailableReason
+        });
+        return;
+      }
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      if (error.code !== "ENOENT") {
+        diagnose("SKILL_INVALID", lexicalFile, "\u6280\u80FD\u6587\u4EF6\u683C\u5F0F\u3001\u5927\u5C0F\u6216\u8BFB\u53D6\u6821\u9A8C\u5931\u8D25");
+        return;
+      }
+    }
+    const names = [];
+    try {
+      const dir = await fs5.opendir(directory);
+      for await (const item of dir) {
+        entries++;
+        if (entries > SKILL_LIMITS.entries) {
+          diagnose("SKILL_SCAN_LIMIT", directory, "\u6280\u80FD\u76EE\u5F55\u6761\u76EE\u8D85\u9650\uFF0C\u672C\u76EE\u5F55\u4E0D\u8FDB\u884C\u90E8\u5206\u968F\u673A\u53D1\u73B0");
+          return;
+        }
+        if (![".git", "node_modules", "dist"].includes(item.name)) names.push(item.name);
+      }
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      diagnose("SKILL_SCAN_FAILED", directory, "\u6280\u80FD\u76EE\u5F55\u65E0\u6CD5\u904D\u5386");
+      return;
+    }
+    names.sort(compareSkillPaths);
+    for (const name of names) {
+      signal?.throwIfAborted();
+      const target = path5.join(directory, name);
+      try {
+        const stat = await fs5.stat(target);
+        if (stat.isDirectory() && !ignored(target, true)) await walk(target, depth + 1, rules);
+      } catch (error) {
+        if (signal?.aborted) throw error;
+        diagnose("SKILL_SCAN_FAILED", target, "\u626B\u63CF\u6761\u76EE\u65E0\u6CD5\u89E3\u6790");
+      }
+    }
+  };
+  await walk(path5.resolve(root.path), 0, []);
+  return result;
+}
+
+// src/capabilities/skills/content.ts
+function validSource(source, text) {
+  return !!source && source.version === 1 && typeof source.name === "string" && isSkillName(source.name) && ["project", "global", "builtin"].includes(source.scope) && ["user", "model"].includes(source.caller) && typeof source.filePath === "string" && typeof source.baseDir === "string" && typeof source.runId === "string" && typeof source.invocationId === "string" && /^[a-f0-9]{64}$/.test(source.contentDigest) && skillDigest(text) === source.renderedDigest;
+}
+function findSkillContent(history, source) {
+  for (let index2 = history.length - 1; index2 >= 0; index2--) {
+    const message = history[index2];
+    for (const block of message.content) {
+      if (block.type !== "text" && block.type !== "tool_result") continue;
+      const found = block.skillSource;
+      if (validSource(found, block.type === "text" ? block.text : block.content) && found.name === source.name && found.filePath === source.filePath && found.contentDigest === source.contentDigest && found.renderedDigest === source.renderedDigest)
+        return { messageId: message.id ?? "", source: found };
+    }
+  }
+  return void 0;
+}
+function inspectSkillContent(raw, projected) {
+  const sources = /* @__PURE__ */ new Map();
+  for (const message of raw)
+    for (const block of message.content) {
+      if (block.type !== "text" && block.type !== "tool_result") continue;
+      const source = block.skillSource;
+      if (!validSource(source, block.type === "text" ? block.text : block.content)) continue;
+      sources.set(JSON.stringify([source.name, source.filePath, source.contentDigest]), {
+        source: structuredClone(source),
+        messageId: message.id ?? "",
+        state: findSkillContent(projected, source) ? "present" : "requires_reload"
+      });
+    }
+  return [...sources.values()];
+}
+function renderSkillReloads(covered) {
+  const states = inspectSkillContent(covered, []);
+  if (!states.length) return "";
+  return `
+[Historical skill bodies removed; reactivate through the current loader before use]
+${JSON.stringify(
+    {
+      skills: states.slice(-50).map(({ source, messageId }) => ({
+        name: source.name,
+        contentDigest: source.contentDigest,
+        renderedDigest: source.renderedDigest,
+        sourceMessageId: messageId,
+        invocationId: source.invocationId,
+        state: "requires_reload"
+      })),
+      omitted: Math.max(0, states.length - 50)
+    }
+  )}`;
+}
 
 // src/context/summary.ts
-import path4 from "path";
+import path6 from "path";
 function truncateToolOutput(text, maximum = 2e3) {
   if (!Number.isSafeInteger(maximum) || maximum < 2) throw new Error("Invalid tool output limit");
   const points = Array.from(text);
@@ -1559,9 +2126,9 @@ function extractFileDetails(history, _projectRoot, previous) {
       if (!["read_file", "write_file", "edit_file"].includes(call.name) || call.source !== void 0 && call.source !== "builtin" || typeof call.input.path !== "string")
         continue;
       const result = results.find((r) => r.toolUseId === call.id);
-      const executionRoot = typeof call.executionRoot === "string" && path4.isAbsolute(call.executionRoot) ? call.executionRoot : void 0;
+      const executionRoot = typeof call.executionRoot === "string" && path6.isAbsolute(call.executionRoot) ? call.executionRoot : void 0;
       const observation = {
-        path: (path4.isAbsolute(call.input.path) ? path4.resolve(call.input.path) : executionRoot ? path4.resolve(executionRoot, call.input.path) : call.input.path).replaceAll("\\", "/"),
+        path: (path6.isAbsolute(call.input.path) ? path6.resolve(call.input.path) : executionRoot ? path6.resolve(executionRoot, call.input.path) : call.input.path).replaceAll("\\", "/"),
         sourceMessageId: assistant.id,
         toolCallId: call.id,
         operation: call.name
@@ -1781,7 +2348,7 @@ var SummaryService = class {
 
 // src/context/manager.ts
 var POLICY_VERSION = 1;
-var digest = (value) => createHash5("sha256").update(stableSerialize(value)).digest("hex");
+var digest = (value) => createHash6("sha256").update(stableSerialize(value)).digest("hex");
 function createRequestBudget(profile, request) {
   const profileBudget = createContextBudget(profile.contextWindow, profile.maxOutputTokens);
   if (request.maxTokens === void 0) return profileBudget;
@@ -1886,7 +2453,7 @@ var ContextManager = class {
             block.content = target.description;
       }
     }
-    if (this.checkpoint) view.unshift(this.summaryMessage(this.checkpoint));
+    if (this.checkpoint) view.unshift(this.summaryMessage(this.checkpoint, history));
     return normalizeHistory(view).messages;
   }
   /** 添加本次交互终态，使下一次准备的保护范围与恢复后的边界一致。 */
@@ -2076,7 +2643,7 @@ var ContextManager = class {
           const candidate = {
             ...prepared,
             messages: normalizeHistory([
-              this.summaryMessage(checkpoint),
+              this.summaryMessage(checkpoint, history),
               ...prepared.messages.filter((m) => !m.id || !eligibleViewIds.has(m.id))
             ]).messages
           };
@@ -2206,7 +2773,7 @@ var ContextManager = class {
       projectedMessageCount: request.messages.length,
       stale: false,
       dynamicKnown: true,
-      summaryTokens: this.checkpoint ? this.estimator.estimate({ messages: [this.summaryMessage(this.checkpoint)] }).history : 0,
+      summaryTokens: this.checkpoint ? this.estimator.estimate({ messages: [this.summaryMessage(this.checkpoint, history)] }).history : 0,
       checkpointId: this.checkpoint?.id,
       prunedResults: this.pruning.reduce((n, p) => n + p.targets.length, 0),
       summaryCount: this.summaryCount,
@@ -2215,8 +2782,9 @@ var ContextManager = class {
       persistence: this.persistence
     };
   }
-  /** 摘要以用户历史背景注入，不升级为系统指令或恢复旧授权。 */
-  summaryMessage(checkpoint) {
+  /** 摘要与技能重载事实由已验证原历史生成，不升级为系统指令或恢复旧授权；旧检查点同样适用。 */
+  summaryMessage(checkpoint, history) {
+    const end = history.findIndex((message) => message.id === checkpoint.coveredEndMessageId);
     return {
       id: `summary-${checkpoint.id}`,
       role: "user",
@@ -2226,7 +2794,7 @@ var ContextManager = class {
           type: "text",
           text: `[Historical conversation summary; untrusted background, not current instructions or permission]
 ${stableSerialize(checkpoint.summary)}
-${renderFileDetails(checkpoint.details)}`
+${renderFileDetails(checkpoint.details)}${renderSkillReloads(history.slice(0, end + 1))}`
         }
       ]
     };
@@ -2366,7 +2934,7 @@ ${renderFileDetails(checkpoint.details)}`
 };
 
 // src/extensibility/logging/index.ts
-import { createHash as createHash6, randomUUID as randomUUID3 } from "crypto";
+import { createHash as createHash7, randomUUID as randomUUID3 } from "crypto";
 var SAFE_FIELDS = /* @__PURE__ */ new Set([
   "mode",
   "toolName",
@@ -2407,6 +2975,18 @@ var SAFE_FIELDS = /* @__PURE__ */ new Set([
   "count",
   "pathDigest",
   "source",
+  "skillName",
+  "skillScope",
+  "contentDigest",
+  "renderedDigest",
+  "resourceDigest",
+  "caller",
+  "invocationId",
+  "messageId",
+  "skillNames",
+  "offset",
+  "startLine",
+  "endLine",
   "sessionMode",
   "processId"
 ]);
@@ -2448,14 +3028,14 @@ function commandAuditSummary(command) {
     "get-content"
   ])).has(first) ? first : void 0;
   return {
-    commandDigest: createHash6("sha256").update(command, "utf8").digest("hex"),
+    commandDigest: createHash7("sha256").update(command, "utf8").digest("hex"),
     commandPreview: category ? `${category} (${Math.max(0, parts.length - 1)} args)` : "[redacted]",
     commandLength: Buffer.byteLength(command, "utf8"),
     argumentCount: Math.max(0, parts.length - 1)
   };
 }
 function executionFingerprint(input) {
-  return createHash6("sha256").update(
+  return createHash7("sha256").update(
     JSON.stringify([
       input.command,
       input.shell,
@@ -2513,9 +3093,9 @@ var StructuredLogger = class {
 };
 
 // src/extensibility/logging/file-sink.ts
-import fs5 from "fs";
+import fs6 from "fs";
 import os2 from "os";
-import path5 from "path";
+import path7 from "path";
 import readline from "readline";
 var FileLogSink = class {
   directory;
@@ -2524,7 +3104,7 @@ var FileLogSink = class {
   retentionDays;
   sync;
   constructor(options) {
-    this.directory = path5.resolve(options.directory);
+    this.directory = path7.resolve(options.directory);
     this.prefix = options.prefix;
     this.maxBytes = options.maxBytes ?? 10 * 1024 * 1024;
     this.retentionDays = options.prefix === "audit" ? void 0 : options.retentionDays;
@@ -2536,32 +3116,32 @@ var FileLogSink = class {
     const bytes = Buffer.byteLength(line, "utf8");
     const date = event.timestamp.slice(0, 10);
     if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) throw new Error("Invalid log timestamp");
-    fs5.mkdirSync(this.directory, { recursive: true, mode: 448 });
+    fs6.mkdirSync(this.directory, { recursive: true, mode: 448 });
     const filePath = this.chooseFile(date, bytes);
-    const descriptor = fs5.openSync(filePath, "a", 384);
+    const descriptor = fs6.openSync(filePath, "a", 384);
     try {
-      fs5.writeSync(descriptor, line, void 0, "utf8");
-      if (this.sync) fs5.fsyncSync(descriptor);
+      fs6.writeSync(descriptor, line, void 0, "utf8");
+      if (this.sync) fs6.fsyncSync(descriptor);
     } finally {
-      fs5.closeSync(descriptor);
+      fs6.closeSync(descriptor);
     }
     if (this.retentionDays !== void 0) this.cleanupExpired(date);
   }
   /** 返回该通道已占用的字节数，供宿主提示长期保留的审计用量。 */
   getUsageBytes() {
-    if (!fs5.existsSync(this.directory)) return 0;
-    return fs5.readdirSync(this.directory).filter((name) => this.isOwnedFile(name)).reduce((total, name) => total + fs5.statSync(path5.join(this.directory, name)).size, 0);
+    if (!fs6.existsSync(this.directory)) return 0;
+    return fs6.readdirSync(this.directory).filter((name) => this.isOwnedFile(name)).reduce((total, name) => total + fs6.statSync(path7.join(this.directory, name)).size, 0);
   }
   /** 优先写入当天未满的最后一个序号文件，超限或无同名文件时开下一个序号。 */
   chooseFile(date, bytes) {
-    const names = fs5.readdirSync(this.directory).filter((name) => name.startsWith(`${this.prefix}-${date}-`) && this.isOwnedFile(name)).sort();
+    const names = fs6.readdirSync(this.directory).filter((name) => name.startsWith(`${this.prefix}-${date}-`) && this.isOwnedFile(name)).sort();
     const lastName = names.at(-1);
     if (lastName) {
-      const lastPath = path5.join(this.directory, lastName);
-      if (fs5.statSync(lastPath).size + bytes <= this.maxBytes) return lastPath;
+      const lastPath = path7.join(this.directory, lastName);
+      if (fs6.statSync(lastPath).size + bytes <= this.maxBytes) return lastPath;
     }
     const next = lastName ? Number(lastName.slice(-9, -6)) + 1 : 1;
-    return path5.join(
+    return path7.join(
       this.directory,
       `${this.prefix}-${date}-${String(next).padStart(3, "0")}.jsonl`
     );
@@ -2570,11 +3150,11 @@ var FileLogSink = class {
   cleanupExpired(currentDate) {
     const current = Date.parse(`${currentDate}T00:00:00.000Z`);
     const cutoff = current - (this.retentionDays ?? 0) * 864e5;
-    for (const name of fs5.readdirSync(this.directory)) {
+    for (const name of fs6.readdirSync(this.directory)) {
       if (!this.isOwnedFile(name)) continue;
       const fileDate = name.slice(this.prefix.length + 1, this.prefix.length + 11);
       if (Date.parse(`${fileDate}T00:00:00.000Z`) < cutoff) {
-        fs5.unlinkSync(path5.join(this.directory, name));
+        fs6.unlinkSync(path7.join(this.directory, name));
       }
     }
   }
@@ -2582,27 +3162,27 @@ var FileLogSink = class {
     return new RegExp(`^${this.prefix}-\\d{4}-\\d{2}-\\d{2}-\\d{3}\\.jsonl$`).test(name);
   }
 };
-function createDefaultLogSinks(baseDirectory = path5.join(os2.homedir(), ".kapibala")) {
+function createDefaultLogSinks(baseDirectory = path7.join(os2.homedir(), ".kapibala")) {
   return {
     operationSink: new FileLogSink({
-      directory: path5.join(baseDirectory, "logs"),
+      directory: path7.join(baseDirectory, "logs"),
       prefix: "operation",
       retentionDays: 30
     }),
     auditSink: new FileLogSink({
-      directory: path5.join(baseDirectory, "audit"),
+      directory: path7.join(baseDirectory, "audit"),
       prefix: "audit",
       sync: true
     })
   };
 }
 async function recoverIncompleteAudit(directory) {
-  if (!fs5.existsSync(directory)) return 0;
-  const files = fs5.readdirSync(directory).filter((name) => /^audit-\d{4}-\d{2}-\d{2}-\d{3}\.jsonl$/.test(name)).sort();
+  if (!fs6.existsSync(directory)) return 0;
+  const files = fs6.readdirSync(directory).filter((name) => /^audit-\d{4}-\d{2}-\d{2}-\d{3}\.jsonl$/.test(name)).sort();
   const open = /* @__PURE__ */ new Map();
   for (const name of files) {
     const lines = readline.createInterface({
-      input: fs5.createReadStream(path5.join(directory, name), { encoding: "utf8" }),
+      input: fs6.createReadStream(path7.join(directory, name), { encoding: "utf8" }),
       crlfDelay: Number.POSITIVE_INFINITY
     });
     for await (const line of lines) {
@@ -2650,43 +3230,43 @@ async function recoverIncompleteAudit(directory) {
 }
 
 // src/capabilities/instructions/index.ts
-import fs6 from "fs";
+import fs7 from "fs";
 import os3 from "os";
-import path6 from "path";
+import path8 from "path";
 var MAX_FILE_BYTES = 32 * 1024;
 var MAX_TOTAL_BYTES = 128 * 1024;
 var MAX_LEVELS = 16;
 function canonicalizeOptionalFile(file) {
   try {
-    return fs6.realpathSync.native(file);
+    return fs7.realpathSync.native(file);
   } catch {
-    return path6.resolve(file);
+    return path8.resolve(file);
   }
 }
 function loadInstructions(options) {
-  const root = fs6.realpathSync.native(options.projectRoot);
-  const cwd = fs6.realpathSync.native(options.cwd);
+  const root = fs7.realpathSync.native(options.projectRoot);
+  const cwd = fs7.realpathSync.native(options.cwd);
   const userFile = canonicalizeOptionalFile(
-    options.userFile ?? path6.join(os3.homedir(), ".kapibala", "AGENTS.md")
+    options.userFile ?? path8.join(os3.homedir(), ".kapibala", "AGENTS.md")
   );
-  const relative = path6.relative(root, cwd);
-  if (relative === ".." || relative.startsWith(`..${path6.sep}`) || path6.isAbsolute(relative)) {
+  const relative = path8.relative(root, cwd);
+  if (relative === ".." || relative.startsWith(`..${path8.sep}`) || path8.isAbsolute(relative)) {
     throw new Error("Instruction cwd is outside project root");
   }
-  const segments = relative ? relative.split(path6.sep) : [];
+  const segments = relative ? relative.split(path8.sep) : [];
   if (segments.length + 1 > MAX_LEVELS)
     throw new Error(`Instruction directory chain exceeds ${MAX_LEVELS} levels`);
   const candidates = [userFile];
   let directory = root;
-  candidates.push(path6.join(directory, "AGENTS.md"));
+  candidates.push(path8.join(directory, "AGENTS.md"));
   for (const segment of segments) {
-    directory = path6.join(directory, segment);
-    candidates.push(path6.join(directory, "AGENTS.md"));
+    directory = path8.join(directory, segment);
+    candidates.push(path8.join(directory, "AGENTS.md"));
   }
   const seenPaths = /* @__PURE__ */ new Set();
   const uniqueCandidates = [];
   for (const file of candidates) {
-    const resolved = path6.resolve(file);
+    const resolved = path8.resolve(file);
     const key = process.platform === "win32" ? resolved.toLowerCase() : resolved;
     if (!seenPaths.has(key)) {
       seenPaths.add(key);
@@ -2698,7 +3278,7 @@ function loadInstructions(options) {
   for (const file of uniqueCandidates) {
     let stat;
     try {
-      stat = fs6.lstatSync(file);
+      stat = fs7.lstatSync(file);
     } catch (error) {
       if (error.code === "ENOENT") continue;
       throw new Error(`Cannot inspect instructions at ${file}`, { cause: error });
@@ -2711,7 +3291,7 @@ function loadInstructions(options) {
     if (totalBytes > MAX_TOTAL_BYTES) throw new Error("Instructions exceed 128 KiB total");
     let bytes;
     try {
-      bytes = fs6.readFileSync(file);
+      bytes = fs7.readFileSync(file);
     } catch (error) {
       throw new Error(`Cannot read instructions at ${file}`, { cause: error });
     }
@@ -2729,12 +3309,653 @@ function loadInstructions(options) {
   return { sources, totalBytes };
 }
 
+// src/capabilities/skills/registry.ts
+import fs8 from "fs/promises";
+
+// src/capabilities/skills/catalog.ts
+var estimator = new UnicodeTokenEstimator();
+function estimateSkillTokens(text) {
+  return estimator.estimate({ systemPrompt: text, messages: [] }).system;
+}
+function escapeSkillXml(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function formatSkillCatalog(skills, contextWindow = 32e3, remainingTokens = Number.POSITIVE_INFINITY) {
+  const budget = Math.max(
+    0,
+    Math.min(SKILL_LIMITS.catalogTokens, Math.floor(contextWindow * 0.01), remainingTokens)
+  );
+  const prefix = "# L2.5 Available Skills\nLoad matching skills with load_skill before following their instructions. Reactivate historical skills in each new run. Use list_skills to search omitted skills.\n<available_skills>\n";
+  const entries = [];
+  const render = (count) => `${prefix}${entries.join("\n")}
+</available_skills>${skills.length > count ? `
+${skills.length - count} skills omitted; query list_skills.` : ""}`;
+  for (const skill of skills) {
+    const description = Array.from(skill.description);
+    let length = Math.min(description.length, SKILL_LIMITS.descriptionChars);
+    while (length > 0) {
+      const text2 = description.slice(0, length).join("");
+      const entry = `  <skill><name>${escapeSkillXml(skill.name)}</name><description>${escapeSkillXml(text2)}</description></skill>`;
+      entries.push(entry);
+      if (estimateSkillTokens(render(entries.length)) <= budget) break;
+      entries.pop();
+      length = length > 24 ? Math.floor(length / 2) : 0;
+    }
+  }
+  const candidate = render(entries.length);
+  const text = skills.length && estimateSkillTokens(candidate) <= budget ? candidate : "";
+  return {
+    text,
+    included: text ? entries.length : 0,
+    omitted: skills.length - (text ? entries.length : 0),
+    estimatedTokens: text ? estimateSkillTokens(text) : 0
+  };
+}
+
+// src/capabilities/skills/registry.ts
+var SkillRegistry = class {
+  /** 固定宿主配置副本，外部对象变更不能静默改变本轮发现或信任。 */
+  constructor(options) {
+    this.options = options;
+    this.options = structuredClone(options);
+  }
+  options;
+  definitions = /* @__PURE__ */ new Map();
+  warnings = [];
+  revisionValue = "";
+  /** 获取独立诊断副本，调用方不能修改生效候选或权限。 */
+  get diagnostics() {
+    return structuredClone(this.warnings);
+  }
+  /** 快照游标身份随正文、来源、可用性变化而失效。 */
+  get revision() {
+    return this.revisionValue;
+  }
+  /** 是否由宿主启用；关闭只影响本次能力，不删除历史或文件。 */
+  get enabled() {
+    return this.options.enabled !== false;
+  }
+  /** 每轮开始重新发现；取消不发布半个快照，非法单文件只产生诊断。 */
+  async refresh(signal) {
+    const candidates = [];
+    const diagnostics = [];
+    for (const root of this.options.roots) {
+      const result = await scanSkillRoot(root, signal);
+      candidates.push(...result.skills);
+      diagnostics.push(...result.diagnostics);
+    }
+    candidates.sort((a, b) => a.priority - b.priority || compareSkillPaths(a.filePath, b.filePath));
+    const definitions = /* @__PURE__ */ new Map();
+    const physical = /* @__PURE__ */ new Set();
+    const disabled = new Set(this.options.disabled ?? []);
+    for (const candidate of candidates) {
+      candidate.disabled = !this.enabled || disabled.has(candidate.name);
+      const existing = definitions.get(candidate.name);
+      if (existing?.available) {
+        diagnostics.push({
+          code: "SKILL_SHADOWED",
+          level: "warn",
+          path: candidate.filePath,
+          message: "\u540C\u540D\u6280\u80FD\u88AB\u66F4\u9AD8\u4F18\u5148\u7EA7\u6765\u6E90\u8986\u76D6",
+          winnerPath: existing.filePath,
+          loserPath: candidate.filePath
+        });
+        continue;
+      }
+      if (!candidate.available && existing) continue;
+      const identity = skillPathKey(candidate.filePath);
+      if (physical.has(identity)) continue;
+      if (candidate.available) physical.add(identity);
+      definitions.set(candidate.name, candidate);
+    }
+    signal?.throwIfAborted();
+    this.definitions = definitions;
+    this.warnings = diagnostics;
+    this.revisionValue = skillDigest(
+      JSON.stringify(
+        [...definitions.values()].map((s) => [
+          s.name,
+          s.scope,
+          s.priority,
+          s.sourceRoot,
+          s.filePath,
+          s.contentDigest,
+          s.available,
+          s.disabled,
+          s.modelInvocable
+        ])
+      )
+    );
+  }
+  /** 按名称查询胜出元数据副本；未知名称返回 undefined，正文仅由 load 校验后懒读取。 */
+  get(name) {
+    const value = this.definitions.get(name);
+    return value ? structuredClone(value) : void 0;
+  }
+  /** 宿主可检查不可用条目；模型/用户视图分别施加调用控制，均不读取正文。 */
+  list(caller = "host", query = "") {
+    const needle = query.toLowerCase();
+    return [...this.definitions.values()].filter(
+      (s) => caller === "host" || s.available && !s.disabled && (caller === "model" ? s.modelInvocable : s.userInvocable)
+    ).filter(
+      (s) => !needle || `${s.name} ${s.description} ${s.when ?? ""}`.toLowerCase().includes(needle)
+    ).sort((a, b) => a.priority - b.priority || compareSkillPaths(a.name, b.name)).map((metadata) => structuredClone(metadata));
+  }
+  /** 按当前快照校验调用控制与物理身份，不接受模型提供的信任或 caller 升级。 */
+  async load(name, caller, signal) {
+    const skill = this.get(name);
+    if (!skill) throw skillFailure("SKILL_NOT_FOUND", "\u6280\u80FD\u4E0D\u5B58\u5728\uFF0C\u8BF7\u67E5\u8BE2\u5F53\u524D\u6280\u80FD\u5217\u8868");
+    if (skill.disabled) throw skillFailure("SKILL_INVOCATION_FORBIDDEN", "\u6280\u80FD\u5DF2\u7531\u5BBF\u4E3B\u7981\u7528");
+    if (!skill.available)
+      throw skillFailure(
+        skill.unavailableReason?.includes("\u4FE1\u4EFB") ? "SKILL_UNTRUSTED" : "SKILL_UNSUPPORTED",
+        skill.unavailableReason ?? "\u6280\u80FD\u4E0D\u53EF\u6267\u884C"
+      );
+    if (!(caller === "model" ? skill.modelInvocable : skill.userInvocable))
+      throw skillFailure("SKILL_INVOCATION_FORBIDDEN", "\u5F53\u524D\u8C03\u7528\u65B9\u4E0D\u80FD\u6FC0\u6D3B\u6B64\u6280\u80FD");
+    const raw = await this.verify(skill, signal);
+    return { ...skill, body: parseSkillDocument(raw, skill.filePath).body };
+  }
+  /** 查询可信模型集合；过期游标可修正，预算不足不返回不前进的分页。 */
+  queryModel(input = {}, remainingTokens = SKILL_LIMITS.queryTokens) {
+    const limit = input.limit ?? 20;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 50 || input.query !== void 0 && (typeof input.query !== "string" || Array.from(input.query).length > 512))
+      throw skillFailure("SKILL_INVALID_INPUT", "\u67E5\u8BE2\u53C2\u6570\u5FC5\u987B\u662F\u6709\u754C\u6587\u672C\u548C1\u201350\u6761\u5206\u9875");
+    const query = input.query?.toLowerCase() ?? "";
+    const queryDigest = skillDigest(query);
+    const skills = this.list("model", query);
+    let offset = 0;
+    if (input.cursor !== void 0) {
+      try {
+        if (typeof input.cursor !== "string" || input.cursor.length > 512 || !/^[a-zA-Z0-9_-]+$/.test(input.cursor))
+          throw new Error("invalid");
+        const value = JSON.parse(Buffer.from(input.cursor, "base64url").toString("utf8"));
+        if (value.revision !== this.revision || value.query !== queryDigest)
+          throw skillFailure("SKILL_CURSOR_EXPIRED", "\u67E5\u8BE2\u5FEB\u7167\u6216\u6761\u4EF6\u5DF2\u53D8\u5316\uFF0C\u8BF7\u91CD\u65B0\u67E5\u8BE2");
+        if (!Number.isSafeInteger(value.offset) || value.offset < 0 || value.offset > skills.length)
+          throw new Error("invalid");
+        offset = value.offset;
+      } catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "SKILL_CURSOR_EXPIRED")
+          throw error;
+        throw skillFailure("SKILL_INVALID_INPUT", "\u6280\u80FD\u67E5\u8BE2\u6E38\u6807\u65E0\u6548");
+      }
+    }
+    const page = { skills: [], total: skills.length };
+    const finalize = () => {
+      const next = offset + page.skills.length;
+      page.nextCursor = next < skills.length ? Buffer.from(
+        JSON.stringify({ revision: this.revision, query: queryDigest, offset: next })
+      ).toString("base64url") : void 0;
+    };
+    const budget = Math.max(0, Math.min(SKILL_LIMITS.queryTokens, remainingTokens));
+    for (const skill of skills.slice(offset, offset + limit)) {
+      const description = Array.from(skill.description);
+      let length = Math.min(description.length, SKILL_LIMITS.descriptionChars);
+      let accepted = false;
+      while (length > 0) {
+        page.skills.push({
+          name: skill.name,
+          description: description.slice(0, length).join(""),
+          scope: skill.scope,
+          ...skill.argumentHint ? { argumentHint: Array.from(skill.argumentHint).slice(0, 100).join("") } : {}
+        });
+        finalize();
+        if (estimateSkillTokens(JSON.stringify(page, null, 2)) <= budget) {
+          accepted = true;
+          break;
+        }
+        page.skills.pop();
+        length = length > 24 ? Math.floor(length / 2) : 0;
+      }
+      if (!accepted) break;
+    }
+    finalize();
+    if (offset < skills.length && !page.skills.length || estimateSkillTokens(JSON.stringify(page, null, 2)) > budget)
+      throw skillFailure("SKILL_BODY_BUDGET_EXCEEDED", "\u5269\u4F59\u4E0A\u4E0B\u6587\u65E0\u6CD5\u5BB9\u7EB3\u6700\u5C0F\u6280\u80FD\u67E5\u8BE2\u54CD\u5E94");
+    return page;
+  }
+  /** 复核配置根、词法发现路径和原文件字节，返回本次有界读取文本；漂移要求新运行，不能热替换。 */
+  async verify(skill, signal) {
+    try {
+      const root = await fs8.realpath(skill.discoveryRoot);
+      const target = await fs8.realpath(skill.discoveryPath);
+      if (skillPathKey(root) !== skillPathKey(skill.sourceRoot) || skillPathKey(target) !== skillPathKey(skill.filePath))
+        throw new Error("changed");
+      const raw = await readBoundedSkillText(target, SKILL_LIMITS.fileBytes, signal);
+      if (skillDigest(raw) !== skill.contentDigest) throw new Error("changed");
+      return raw;
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      throw skillFailure("SKILL_CHANGED", "\u6280\u80FD\u6587\u4EF6\u6216\u6765\u6E90\u5DF2\u53D8\u5316\uFF0C\u8BF7\u5F00\u59CB\u65B0\u8FD0\u884C\u5237\u65B0");
+    }
+  }
+};
+
+// src/capabilities/skills/policy.ts
+var aliases = {
+  Read: "read_file",
+  Write: "write_file",
+  Glob: "glob",
+  Grep: "grep",
+  Bash: "run_command"
+};
+function normalizeSkillTools(skill, tools) {
+  if (skill.allowedTools === void 0) return void 0;
+  const names = new Set(tools.map((tool) => tool.name));
+  const normalized = /* @__PURE__ */ new Set();
+  for (const raw of skill.allowedTools) {
+    const mapped = aliases[raw] ?? raw;
+    if (/[*?()]/.test(raw) || !aliases[raw] && !names.has(mapped))
+      throw skillFailure(
+        "SKILL_UNSUPPORTED",
+        "\u6280\u80FD\u58F0\u660E\u4E86\u672A\u77E5\u5DE5\u5177\u6216\u53C2\u6570\u6A21\u5F0F\uFF0C\u8BF7\u8FC1\u79FB\u4E3A\u5BBF\u4E3B\u7CBE\u786E\u6743\u9650\u89C4\u5219"
+      );
+    normalized.add(mapped);
+  }
+  return normalized;
+}
+function intersectSkillTools(activations) {
+  let allowed;
+  for (const item of activations) {
+    if (item.allowedTools === void 0) continue;
+    allowed = allowed === void 0 ? new Set(item.allowedTools) : new Set([...allowed].filter((name) => item.allowedTools.has(name)));
+  }
+  return allowed;
+}
+
+// src/capabilities/skills/resources.ts
+import fs9 from "fs/promises";
+import path9 from "path";
+async function readSkillResource(skill, input, signal) {
+  if (typeof input.path !== "string" || !input.path || input.path.length > 4096 || path9.win32.isAbsolute(input.path) || path9.posix.isAbsolute(input.path) || /^[a-zA-Z]:/.test(input.path))
+    throw skillFailure("SKILL_RESOURCE_DENIED", "\u8D44\u6E90\u5FC5\u987B\u4F7F\u7528\u6280\u80FD\u76EE\u5F55\u5185\u7684\u76F8\u5BF9\u8DEF\u5F84");
+  const start = input.startLine ?? 1;
+  const end = input.endLine;
+  const offset = input.offset ?? 0;
+  if (!Number.isSafeInteger(start) || start < 1 || end !== void 0 && (!Number.isSafeInteger(end) || end < start) || !Number.isSafeInteger(offset) || offset < 0 || input.offset !== void 0 && (input.startLine !== void 0 || end !== void 0))
+    throw skillFailure("SKILL_INVALID_INPUT", "\u8D44\u6E90\u884C\u8303\u56F4\u6216\u5B57\u8282\u7EED\u8BFB\u53C2\u6570\u65E0\u6548");
+  const lexical = path9.resolve(skill.baseDir, input.path.split(/[\\/]/).join(path9.sep));
+  if (!isWithinSkillRoot(skill.baseDir, lexical))
+    throw skillFailure("SKILL_RESOURCE_DENIED", "\u8D44\u6E90\u8DEF\u5F84\u79BB\u5F00\u6280\u80FD\u6839\u76EE\u5F55");
+  let actual;
+  try {
+    actual = await fs9.realpath(lexical);
+  } catch {
+    throw skillFailure("SKILL_RESOURCE_DENIED", "\u8D44\u6E90\u4E0D\u5B58\u5728\u6216\u94FE\u63A5\u65E0\u6CD5\u89E3\u6790");
+  }
+  if (!isWithinSkillRoot(skill.baseDir, actual))
+    throw skillFailure("SKILL_RESOURCE_DENIED", "\u8D44\u6E90\u7269\u7406\u8DEF\u5F84\u79BB\u5F00\u6280\u80FD\u6839\u76EE\u5F55");
+  signal?.throwIfAborted();
+  const handle = await fs9.open(actual, "r");
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || offset > stat.size)
+      throw skillFailure("SKILL_RESOURCE_DENIED", "\u8D44\u6E90\u4E0D\u662F\u6709\u6548\u6587\u672C\u6587\u4EF6\u6216\u7EED\u8BFB\u8303\u56F4\u5DF2\u5931\u6548");
+    const decoder = new TextDecoder("utf8", { fatal: true, ignoreBOM: true });
+    const output = [];
+    let bytes = 0;
+    let position = offset;
+    let consumed = offset;
+    let line = 1;
+    const consume = (text) => {
+      for (const character of text) {
+        if (character === "\0") throw skillFailure("SKILL_RESOURCE_DENIED", "\u4E0D\u652F\u6301\u4E8C\u8FDB\u5236\u8D44\u6E90");
+        if (end !== void 0 && line > end) return { text: output.join(""), truncated: false };
+        const length = Buffer.byteLength(character);
+        if (line >= start) {
+          if (bytes + length > SKILL_LIMITS.resourceBytes)
+            return { text: output.join(""), truncated: true, nextOffset: consumed };
+          output.push(character);
+          bytes += length;
+        }
+        consumed += length;
+        if (character === "\n") line++;
+      }
+      return void 0;
+    };
+    while (position < stat.size) {
+      signal?.throwIfAborted();
+      const buffer = Buffer.alloc(Math.min(16 * 1024, stat.size - position));
+      const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
+      if (!bytesRead) break;
+      position += bytesRead;
+      let text;
+      try {
+        text = decoder.decode(buffer.subarray(0, bytesRead), { stream: true });
+      } catch {
+        throw skillFailure("SKILL_RESOURCE_DENIED", "\u8D44\u6E90\u4E0D\u662F\u6709\u6548 UTF-8 \u6587\u672C\u6216\u7EED\u8BFB\u4E0D\u5728\u5B57\u7B26\u8FB9\u754C");
+      }
+      const result = consume(text);
+      if (result) return result;
+    }
+    try {
+      const result = consume(decoder.decode());
+      if (result) return result;
+    } catch {
+      throw skillFailure("SKILL_RESOURCE_DENIED", "\u8D44\u6E90\u4E0D\u662F\u5B8C\u6574 UTF-8 \u6587\u672C");
+    }
+    return { text: output.join(""), truncated: false };
+  } finally {
+    await handle.close();
+  }
+}
+async function listSkillResources(skill, signal) {
+  const files = [];
+  const visited = /* @__PURE__ */ new Set();
+  let entries = 0;
+  let truncated = false;
+  const walk = async (directory, depth) => {
+    if (depth > SKILL_LIMITS.depth || files.length > SKILL_LIMITS.resourceFiles || entries >= SKILL_LIMITS.entries || visited.size >= SKILL_LIMITS.directories) {
+      truncated = true;
+      return;
+    }
+    signal?.throwIfAborted();
+    const actual = await fs9.realpath(directory);
+    if (!isWithinSkillRoot(skill.baseDir, actual) || visited.has(skillPathKey(actual))) return;
+    visited.add(skillPathKey(actual));
+    const dir = await fs9.opendir(directory);
+    const names = [];
+    for await (const item of dir) {
+      if (++entries > SKILL_LIMITS.entries) return;
+      if (![".git", "node_modules", "dist", "SKILL.md"].includes(item.name)) names.push(item.name);
+    }
+    names.sort();
+    for (const name of names) {
+      if (files.length > SKILL_LIMITS.resourceFiles) return;
+      const target = path9.join(directory, name);
+      try {
+        const real = await fs9.realpath(target);
+        if (!isWithinSkillRoot(skill.baseDir, real)) continue;
+        const stat = await fs9.stat(real);
+        if (stat.isDirectory()) await walk(target, depth + 1);
+        else if (stat.isFile())
+          files.push(path9.relative(skill.baseDir, target).split(path9.sep).join("/"));
+      } catch (error) {
+        if (signal?.aborted) throw error;
+      }
+    }
+  };
+  await walk(skill.baseDir, 0);
+  return {
+    files: files.slice(0, SKILL_LIMITS.resourceFiles),
+    truncated: truncated || files.length > SKILL_LIMITS.resourceFiles || entries >= SKILL_LIMITS.entries
+  };
+}
+
+// src/capabilities/skills/loader.ts
+import { randomUUID as randomUUID4 } from "crypto";
+
+// src/capabilities/tools/index.ts
+function defineTool(tool) {
+  return tool;
+}
+function toToolDefinition(tool) {
+  return {
+    name: tool.name,
+    description: tool.description,
+    parameters: tool.parameters
+  };
+}
+
+// src/capabilities/skills/loader.ts
+function skillUnitTokens(text, source) {
+  const block = source.caller === "user" ? { type: "text", text, skillSource: source } : { type: "tool_result", toolUseId: source.invocationId, content: text, skillSource: source };
+  return estimateSkillTokens(JSON.stringify(block)) + 32;
+}
+var SkillRuntime = class {
+  /** 注册表和工具集合属于一个Session；不跨会话共享授权或隐式目录。 */
+  constructor(registry, tools, onResourceRead) {
+    this.registry = registry;
+    this.tools = tools;
+    this.onResourceRead = onResourceRead;
+    this.loaderTool = defineTool({
+      name: "load_skill",
+      description: "Load full instructions for a matching skill. Use list_skills to discover skills omitted from the catalog. Reactivate historical skills in each new run.",
+      metadata: { source: "builtin", permissions: ["fs:read"] },
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        required: ["name"],
+        properties: { name: { type: "string" } }
+      },
+      execute: async (input, context) => {
+        if (typeof input.name !== "string")
+          throw skillFailure("SKILL_INVALID_INPUT", "\u6280\u80FD\u540D\u79F0\u5FC5\u987B\u662F\u5B57\u7B26\u4E32");
+        const loaded = await this.prepare(input.name, "model", context.signal);
+        this.prepared.set(loaded.text, loaded);
+        return loaded.text;
+      }
+    });
+    this.queryTool = defineTool({
+      name: "list_skills",
+      description: "Search trusted model-callable skill metadata, including skills omitted from the prompt. Pagination does not activate a skill.",
+      metadata: { source: "builtin", permissions: ["fs:read"] },
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          query: { type: "string" },
+          cursor: { type: "string" },
+          limit: { type: "integer", minimum: 1, maximum: 50 }
+        }
+      },
+      execute: async (input) => this.registry.queryModel(input, this.remaining())
+    });
+    this.resourceTool = defineTool({
+      name: "read_skill_resource",
+      description: "Read a text resource inside an activated, committed skill. Follow nextOffset using offset for large UTF-8 resources; do not combine offset with line ranges. This never executes scripts.",
+      metadata: { source: "builtin", permissions: ["fs:read"] },
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        required: ["name", "path"],
+        properties: {
+          name: { type: "string" },
+          path: { type: "string" },
+          startLine: { type: "integer", minimum: 1 },
+          endLine: { type: "integer", minimum: 1 },
+          offset: { type: "integer", minimum: 0 }
+        }
+      },
+      execute: async (input, context) => this.readResource(input, context.signal)
+    });
+    this.controls = /* @__PURE__ */ new Set([this.loaderTool, this.queryTool, this.resourceTool]);
+  }
+  registry;
+  tools;
+  onResourceRead;
+  loaderTool;
+  queryTool;
+  resourceTool;
+  controls;
+  prepared = /* @__PURE__ */ new Map();
+  active = /* @__PURE__ */ new Map();
+  runId = "";
+  history = () => [];
+  projection = () => [];
+  reservedTokens = 0;
+  remaining = () => 0;
+  /**
+   * 开始新运行；历史正文只作事实，必须由本轮加载重新激活。
+   * remaining 必须扣除在途 assistant 和普通工具结果；尚未提交的成功技能正文由本类独立预留，不重复扣除。
+   */
+  begin(runId, history, remaining, projection = history) {
+    this.clear();
+    this.runId = runId;
+    this.history = history;
+    this.projection = projection;
+    this.remaining = remaining;
+  }
+  /** 按实际集合安装实例工具；同名插件不覆盖为受信任工具，也不能制造目录引导。 */
+  syncTools() {
+    const model = this.registry.enabled && this.registry.list("model").length > 0;
+    for (const tool of [this.loaderTool, this.queryTool, this.resourceTool]) {
+      const shouldRegister = tool === this.resourceTool ? model || this.active.size > 0 : model;
+      const existing = this.tools.get(tool.name);
+      if (shouldRegister && !existing) this.tools.register(tool);
+      else if (!shouldRegister && existing === tool) this.tools.unregister(tool.name);
+    }
+  }
+  /** 清空本轮状态；调用方必须先等待工具和历史事务清理，不能提前释放会话锁。 */
+  clear() {
+    this.active.clear();
+    this.prepared.clear();
+    this.runId = "";
+    this.reservedTokens = 0;
+    this.history = () => [];
+    this.projection = () => [];
+    this.remaining = () => 0;
+  }
+  /** 查询本轮活动状态副本，避免宿主修改限制。 */
+  get activations() {
+    return structuredClone([...this.active.values()]);
+  }
+  /** 预检正文、限制和输入空间；调用方由宿主固定，不读取模型伪造caller。 */
+  async prepare(name, caller, signal) {
+    if (!this.runId) throw skillFailure("SKILL_INVOCATION_FORBIDDEN", "\u6280\u80FD\u53EA\u80FD\u5728\u5F53\u524D\u8FD0\u884C\u4E2D\u6FC0\u6D3B");
+    const definition = await this.registry.load(name, caller, signal);
+    const allowedTools = normalizeSkillTools(definition, this.tools.list());
+    const combined = intersectSkillTools([...this.active.values(), { allowedTools }]);
+    const existing = this.active.get(name);
+    if (existing?.state === "committed" && existing.definition.contentDigest === definition.contentDigest && findSkillContent(this.projection(), existing.source)) {
+      return {
+        definition,
+        source: existing.source,
+        allowedTools,
+        alreadyPresent: true,
+        text: JSON.stringify({
+          status: "already_present",
+          name,
+          invocationId: existing.source.invocationId,
+          effectiveTools: combined === void 0 ? "host policy" : [...combined].sort()
+        })
+      };
+    }
+    const resources = await listSkillResources(definition, signal);
+    const text = `<skill_content name="${escapeSkillXml(definition.name)}">
+Scope: ${definition.scope}
+Content digest: ${definition.contentDigest}
+Compatibility: ${definition.compatibility ?? "unspecified"}
+Skill directory: ${definition.baseDir}
+Read relative references with read_skill_resource; script execution still requires normal permissions.
+Effective business tools: ${combined === void 0 ? "host policy" : [...combined].sort().join(", ") || "none"}
+
+${definition.body}
+<skill_resources>
+${resources.files.map((file) => `<file>${escapeSkillXml(file)}</file>`).join("\n")}
+</skill_resources>
+Resources truncated: ${resources.truncated}
+</skill_content>`;
+    const source = {
+      version: 1,
+      name,
+      scope: definition.scope,
+      filePath: definition.filePath,
+      baseDir: definition.baseDir,
+      contentDigest: definition.contentDigest,
+      renderedDigest: skillDigest(text),
+      caller,
+      runId: this.runId,
+      invocationId: randomUUID4()
+    };
+    if (skillUnitTokens(text, source) > this.remaining() - this.reservedTokens)
+      throw skillFailure("SKILL_BODY_BUDGET_EXCEEDED", "\u5269\u4F59\u8F93\u5165\u9884\u7B97\u4E0D\u80FD\u5BB9\u7EB3\u5B8C\u6574\u6280\u80FD\u6B63\u6587");
+    return {
+      definition,
+      text,
+      allowedTools,
+      source
+    };
+  }
+  /** 真实用户入口安装pending；正文需进入用户消息，提交前不提供资源。 */
+  acceptUser(prepared) {
+    if (prepared.source.caller !== "user" || prepared.source.runId !== this.runId)
+      throw skillFailure("SKILL_INVOCATION_FORBIDDEN", "\u6280\u80FD\u7528\u6237\u6765\u6E90\u4E0E\u5F53\u524D\u8FD0\u884C\u4E0D\u7B26");
+    this.active.set(prepared.definition.name, {
+      definition: prepared.definition,
+      source: prepared.source,
+      allowedTools: prepared.allowedTools,
+      state: "pending"
+    });
+  }
+  /** 最终工具结果通过执行器钩子/审计后安装收紧；同名或仿造结果不激活。 */
+  acceptResult(tool, result) {
+    if (tool !== this.loaderTool || result.isError) return;
+    const prepared = this.prepared.get(result.content);
+    if (!prepared)
+      throw skillFailure("SKILL_INVOCATION_FORBIDDEN", "\u52A0\u8F7D\u7ED3\u679C\u65E0\u6CD5\u5173\u8054\u5F53\u524D\u53D7\u4FE1\u4EFB\u9884\u68C0");
+    this.prepared.delete(result.content);
+    if (prepared.alreadyPresent) return;
+    prepared.source.invocationId = result.toolUseId;
+    result.skillSource = structuredClone(prepared.source);
+    this.reservedTokens += skillUnitTokens(result.content, prepared.source);
+    this.active.set(prepared.definition.name, {
+      definition: prepared.definition,
+      source: prepared.source,
+      allowedTools: prepared.allowedTools,
+      state: "pending"
+    });
+  }
+  /** 业务调用的动态硬拒绝；控制工具仅按实例豁免，仍须宿主权限裁决。 */
+  denial(tool) {
+    if (this.controls.has(tool)) return void 0;
+    const allowed = intersectSkillTools(this.active.values());
+    if (allowed !== void 0 && !allowed.has(tool.name))
+      return {
+        code: "SKILL_POLICY_DENIED",
+        message: "\u5DE5\u5177\u4E0D\u5728\u5F53\u524D\u6D3B\u52A8\u6280\u80FD\u5141\u8BB8\u8303\u56F4\u5185",
+        retryPolicy: "never",
+        fields: { skillNames: [...this.active.keys()].sort().join(",") }
+      };
+    return void 0;
+  }
+  /** 完整消息提交后记录审计再发布事件；失败不回滚历史，但不提交资源资格。 */
+  async commit(audit, persistence) {
+    const events = [];
+    for (const activation of this.active.values()) {
+      if (activation.state !== "pending") continue;
+      const found = findSkillContent(this.history(), activation.source);
+      if (!found || found.source.invocationId !== activation.source.invocationId) continue;
+      await audit(activation.source, found.messageId);
+      activation.state = "committed";
+      events.push({
+        type: "skill_loaded",
+        source: structuredClone(activation.source),
+        messageId: found.messageId,
+        persistence
+      });
+    }
+    this.reservedTokens = 0;
+    return events;
+  }
+  /** 检查最终模型投影的完整活动指导；钩子或压缩不能移走后继续执行。 */
+  assertProjection(messages) {
+    for (const activation of this.active.values()) {
+      if (activation.state === "committed" && !findSkillContent(messages, activation.source))
+        throw skillFailure("SKILL_CONTEXT_LOST", "\u5F53\u524D\u6D3B\u52A8\u6280\u80FD\u6B63\u6587\u5DF2\u79BB\u5F00\u8BF7\u6C42\u6295\u5F71\uFF0C\u8BF7\u91CD\u65B0\u5F00\u59CB\u8FD0\u884C");
+    }
+  }
+  /** 只读本轮已提交技能资源；文件/来源漂移要求重新开始，不重放脚本。 */
+  async readResource(input, signal) {
+    if (typeof input.name !== "string")
+      throw skillFailure("SKILL_INVALID_INPUT", "\u6280\u80FD\u540D\u79F0\u5FC5\u987B\u662F\u5B57\u7B26\u4E32");
+    const activation = this.active.get(input.name);
+    if (!activation || activation.state !== "committed")
+      throw skillFailure("SKILL_NOT_COMMITTED", "\u6280\u80FD\u5C1A\u672A\u5728\u672C\u8F6E\u5B8C\u6574\u63D0\u4EA4\uFF0C\u8BF7\u52A0\u8F7D\u540E\u5728\u4E0B\u4E00\u6B65\u8BFB\u53D6");
+    await this.registry.verify(activation.definition, signal);
+    const page = await readSkillResource(activation.definition, input, signal);
+    await this.onResourceRead?.(activation.source, input, page);
+    return page;
+  }
+};
+
 // src/capabilities/shell/detect.ts
 import { spawnSync } from "child_process";
-import { createHash as createHash7 } from "crypto";
-import fs7 from "fs";
+import { createHash as createHash8 } from "crypto";
+import fs10 from "fs";
 import os4 from "os";
-import path7 from "path";
+import path10 from "path";
 function classifyBashOutput(unameOutput, platform) {
   const uname = unameOutput.trim().split(/\r?\n/)[0]?.toLowerCase() ?? "";
   if (platform === "win32") {
@@ -2749,12 +3970,12 @@ function findExecutables(name, pathEnv, platform) {
   const extension = platform === "win32" && !name.toLowerCase().endsWith(".exe") ? ".exe" : "";
   const found = [];
   const seen = /* @__PURE__ */ new Set();
-  for (const directory of pathEnv.split(path7.delimiter)) {
+  for (const directory of pathEnv.split(path10.delimiter)) {
     if (!directory) continue;
-    const candidate = path7.join(directory, name + extension);
+    const candidate = path10.join(directory, name + extension);
     try {
-      if (!fs7.statSync(candidate).isFile()) continue;
-      const real = fs7.realpathSync(candidate);
+      if (!fs10.statSync(candidate).isFile()) continue;
+      const real = fs10.realpathSync(candidate);
       const key = platform === "win32" ? real.toLowerCase() : real;
       if (seen.has(key)) continue;
       seen.add(key);
@@ -2784,12 +4005,12 @@ function probePowerShell(executable, cwd) {
   return result.status === 0 && Boolean(result.stdout?.trim());
 }
 function buildEnvironment(executable, kind, cwd) {
-  const stat = fs7.statSync(executable);
+  const stat = fs10.statSync(executable);
   return {
     kind,
     executable,
     cwd,
-    executableDigest: createHash7("sha256").update(JSON.stringify([executable, stat.size, stat.mtimeMs])).digest("hex")
+    executableDigest: createHash8("sha256").update(JSON.stringify([executable, stat.size, stat.mtimeMs])).digest("hex")
   };
 }
 function candidatesFor(kind, platform, pathEnv) {
@@ -2814,11 +4035,11 @@ function tryKind(kind, platform, pathEnv, cwd) {
   return void 0;
 }
 function detectExplicitPath(preference, cwd, platform) {
-  const executable = fs7.realpathSync(preference);
-  if (!fs7.statSync(executable).isFile()) {
+  const executable = fs10.realpathSync(preference);
+  if (!fs10.statSync(executable).isFile()) {
     throw new Error(`Requested interpreter path is not a file: ${preference}`);
   }
-  const base = path7.basename(executable).toLowerCase();
+  const base = path10.basename(executable).toLowerCase();
   if (/^pwsh(\.exe)?$/.test(base) || /^powershell(_ise)?(\.exe)?$/.test(base)) {
     const kind = base.startsWith("pwsh") ? "pwsh" : "powershell";
     if (platform !== "win32" && kind === "powershell") {
@@ -2841,7 +4062,7 @@ function detectExplicitPath(preference, cwd, platform) {
 }
 function detectShell(options) {
   const platform = options.platform ?? os4.platform();
-  const cwd = fs7.realpathSync(options.cwd);
+  const cwd = fs10.realpathSync(options.cwd);
   const pathEnv = options.pathEnv ?? process.env.PATH ?? "";
   const preference = options.preference ?? "auto";
   if (/[\\/]/.test(preference) || preference.toLowerCase().endsWith(".exe")) {
@@ -2859,24 +4080,10 @@ function detectShell(options) {
 
 // src/capabilities/shell/tool.ts
 import { spawn, spawnSync as spawnSync2 } from "child_process";
-import { createHash as createHash8, randomUUID as randomUUID4 } from "crypto";
-import fs8 from "fs";
-import path8 from "path";
+import { createHash as createHash9, randomUUID as randomUUID5 } from "crypto";
+import fs11 from "fs";
+import path11 from "path";
 import { StringDecoder } from "string_decoder";
-
-// src/capabilities/tools/index.ts
-function defineTool(tool) {
-  return tool;
-}
-function toToolDefinition(tool) {
-  return {
-    name: tool.name,
-    description: tool.description,
-    parameters: tool.parameters
-  };
-}
-
-// src/capabilities/shell/tool.ts
 var INLINE_LIMIT = 64 * 1024;
 var FILE_LIMIT = 16 * 1024 * 1024;
 var DEFAULT_TIMEOUT = 12e4;
@@ -2919,9 +4126,9 @@ function utf8Prefix(bytes, limit) {
   return bytes.subarray(0, end);
 }
 function effectiveCwd(input, rootDir) {
-  const requested = input.cwd ? path8.resolve(rootDir, input.cwd) : rootDir;
-  const real = fs8.realpathSync(requested);
-  if (!fs8.statSync(real).isDirectory())
+  const requested = input.cwd ? path11.resolve(rootDir, input.cwd) : rootDir;
+  const real = fs11.realpathSync(requested);
+  if (!fs11.statSync(real).isDirectory())
     throw new Error("Command working directory is not a directory");
   return real;
 }
@@ -2944,12 +4151,12 @@ function directScriptDigest(command, kind, cwd) {
   const match = bashLike ? /^(?:bash )?\.\/([A-Za-z0-9_./-]+\.sh)$/.exec(normalized) : /^\.\/([A-Za-z0-9_./-]+\.ps1)$/i.exec(normalized);
   if (!match) return void 0;
   try {
-    const script = fs8.realpathSync(path8.resolve(cwd, match[1]));
-    const relative = path8.relative(cwd, script);
-    if (relative.startsWith("..") || path8.isAbsolute(relative)) return void 0;
-    const stat = fs8.statSync(script);
+    const script = fs11.realpathSync(path11.resolve(cwd, match[1]));
+    const relative = path11.relative(cwd, script);
+    if (relative.startsWith("..") || path11.isAbsolute(relative)) return void 0;
+    const stat = fs11.statSync(script);
     if (!stat.isFile() || stat.size > 1024 * 1024) return void 0;
-    return createHash8("sha256").update(script).update("\0").update(fs8.readFileSync(script)).digest("hex");
+    return createHash9("sha256").update(script).update("\0").update(fs11.readFileSync(script)).digest("hex");
   } catch {
     return void 0;
   }
@@ -2964,9 +4171,9 @@ function interpreterArgs(environment, command) {
 function getTaskkillPath() {
   if (process.platform !== "win32") return "taskkill";
   const systemRoot = process.env.SystemRoot ?? process.env.windir ?? "C:\\Windows";
-  const candidate = path8.join(systemRoot, "System32", "taskkill.exe");
+  const candidate = path11.join(systemRoot, "System32", "taskkill.exe");
   try {
-    if (fs8.existsSync(candidate)) return candidate;
+    if (fs11.existsSync(candidate)) return candidate;
   } catch {
   }
   return "taskkill.exe";
@@ -2979,7 +4186,7 @@ function createNativeBashGroup(environment) {
   let accepted = false;
   const group = {
     environment,
-    token: randomUUID4(),
+    token: randomUUID5(),
     ready: new Promise((resolve) => {
       resolveReady = resolve;
     }),
@@ -3103,16 +4310,16 @@ function waitForClose(promise, milliseconds) {
   });
 }
 function resultDirectory(rootDir) {
-  return path8.join(rootDir, ".kapibala", "tool-results");
+  return path11.join(rootDir, ".kapibala", "tool-results");
 }
 function cleanupCommandResults(rootDir, now = Date.now()) {
   const directory = resultDirectory(rootDir);
-  if (!fs8.existsSync(directory)) return;
-  const manifest = path8.join(directory, RESULT_MANIFEST);
-  if (!fs8.existsSync(manifest) || !fs8.lstatSync(manifest).isFile()) return;
+  if (!fs11.existsSync(directory)) return;
+  const manifest = path11.join(directory, RESULT_MANIFEST);
+  if (!fs11.existsSync(manifest) || !fs11.lstatSync(manifest).isFile()) return;
   const cutoff = now - 7 * 864e5;
   const retained = [];
-  for (const line of fs8.readFileSync(manifest, "utf8").split("\n")) {
+  for (const line of fs11.readFileSync(manifest, "utf8").split("\n")) {
     if (!line) continue;
     let record;
     try {
@@ -3121,23 +4328,23 @@ function cleanupCommandResults(rootDir, now = Date.now()) {
       continue;
     }
     if (!OWNED_RESULT.test(record.name)) continue;
-    const file = path8.join(directory, record.name);
-    if (!fs8.existsSync(file)) continue;
-    const stat = fs8.lstatSync(file);
+    const file = path11.join(directory, record.name);
+    if (!fs11.existsSync(file)) continue;
+    const stat = fs11.lstatSync(file);
     if (!stat.isFile() || stat.dev !== record.dev || stat.ino !== record.ino) continue;
-    if (stat.mtimeMs < cutoff) fs8.unlinkSync(file);
+    if (stat.mtimeMs < cutoff) fs11.unlinkSync(file);
     else retained.push(line);
   }
-  const replacement = path8.join(directory, `.managed-results-${randomUUID4()}.tmp`);
-  fs8.writeFileSync(replacement, retained.length ? `${retained.join("\n")}
+  const replacement = path11.join(directory, `.managed-results-${randomUUID5()}.tmp`);
+  fs11.writeFileSync(replacement, retained.length ? `${retained.join("\n")}
 ` : "", { mode: 384 });
-  fs8.renameSync(replacement, manifest);
+  fs11.renameSync(replacement, manifest);
 }
 function recordManagedResult(directory, file, descriptor) {
-  const stat = fs8.fstatSync(descriptor);
-  fs8.appendFileSync(
-    path8.join(directory, RESULT_MANIFEST),
-    `${JSON.stringify({ name: path8.basename(file), dev: stat.dev, ino: stat.ino })}
+  const stat = fs11.fstatSync(descriptor);
+  fs11.appendFileSync(
+    path11.join(directory, RESULT_MANIFEST),
+    `${JSON.stringify({ name: path11.basename(file), dev: stat.dev, ino: stat.ino })}
 `,
     { mode: 384 }
   );
@@ -3169,9 +4376,9 @@ function createRunCommandTool(environment) {
       const cwd = effectiveCwd(input, rootDir);
       const timeoutMs = effectiveTimeout(input);
       const scriptDigest = directScriptDigest(input.command, environment.kind, cwd);
-      const stat = fs8.statSync(environment.executable);
-      const executableDigest = createHash8("sha256").update(JSON.stringify([environment.executable, stat.size, stat.mtimeMs])).digest("hex");
-      const environmentDigest = createHash8("sha256").update(JSON.stringify(limitedEnvironment(environment.kind))).digest("hex");
+      const stat = fs11.statSync(environment.executable);
+      const executableDigest = createHash9("sha256").update(JSON.stringify([environment.executable, stat.size, stat.mtimeMs])).digest("hex");
+      const environmentDigest = createHash9("sha256").update(JSON.stringify(limitedEnvironment(environment.kind))).digest("hex");
       return {
         command: input.command,
         interpreter: environment.kind,
@@ -3233,23 +4440,23 @@ ${input.command}` : input.command;
         }
         if (outputBytes > INLINE_LIMIT && descriptor === void 0) {
           const directory = resultDirectory(ctx.rootDir);
-          fs8.mkdirSync(directory, { recursive: true, mode: 448 });
-          outputFile = path8.join(directory, `run-${randomUUID4()}.txt`);
-          descriptor = fs8.openSync(outputFile, "wx", 384);
+          fs11.mkdirSync(directory, { recursive: true, mode: 448 });
+          outputFile = path11.join(directory, `run-${randomUUID5()}.txt`);
+          descriptor = fs11.openSync(outputFile, "wx", 384);
           recordManagedResult(directory, outputFile, descriptor);
           const prefix = Buffer.concat(inline);
-          fs8.writeSync(descriptor, prefix);
+          fs11.writeSync(descriptor, prefix);
           fileBytes = prefix.length;
           const remaining = chunk.subarray(
             Math.max(0, prefix.length - (outputBytes - chunk.length))
           );
           const writable = utf8Prefix(remaining, FILE_LIMIT - fileBytes);
-          if (writable.length > 0) fs8.writeSync(descriptor, writable);
+          if (writable.length > 0) fs11.writeSync(descriptor, writable);
           fileBytes += writable.length;
           if (writable.length < remaining.length) outputFileTruncated = true;
         } else if (descriptor !== void 0 && !outputFileTruncated) {
           const writable = utf8Prefix(chunk, FILE_LIMIT - fileBytes);
-          if (writable.length > 0) fs8.writeSync(descriptor, writable);
+          if (writable.length > 0) fs11.writeSync(descriptor, writable);
           fileBytes += writable.length;
           if (writable.length < chunk.length) outputFileTruncated = true;
         } else if (descriptor !== void 0) {
@@ -3263,7 +4470,7 @@ ${input.command}` : input.command;
           outputFailure = true;
           if (descriptor !== void 0) {
             try {
-              fs8.closeSync(descriptor);
+              fs11.closeSync(descriptor);
             } catch {
             }
             descriptor = void 0;
@@ -3305,7 +4512,7 @@ ${input.command}` : input.command;
           forceProcessTree(child, nativeGroup);
           await waitForClose(close, 3e3);
         }
-        if (descriptor !== void 0) fs8.closeSync(descriptor);
+        if (descriptor !== void 0) fs11.closeSync(descriptor);
         throw new KapibalaError("Process started but spawn audit failed", {
           code: "OUTCOME_UNKNOWN",
           retryPolicy: "after_user_action",
@@ -3397,18 +4604,18 @@ ${input.command}` : input.command;
         clearTimeout(timer);
         clearInterval(progressTimer);
         ctx.signal?.removeEventListener("abort", onAbort);
-        if (descriptor !== void 0) fs8.closeSync(descriptor);
+        if (descriptor !== void 0) fs11.closeSync(descriptor);
       }
     }
   });
 }
 
 // src/capabilities/security/sandbox.ts
-import fs9 from "fs";
-import path9 from "path";
+import fs12 from "fs";
+import path12 from "path";
 function tryRealpath(target) {
   try {
-    return fs9.realpathSync(target);
+    return fs12.realpathSync(target);
   } catch {
     return void 0;
   }
@@ -3418,7 +4625,7 @@ var PathSandbox = class {
   allowSymlinks;
   cachedRealRootDir;
   constructor(config) {
-    this.rootDir = path9.resolve(config.rootDir);
+    this.rootDir = path12.resolve(config.rootDir);
     this.allowSymlinks = config.allowSymlinks ?? false;
   }
   /**
@@ -3441,16 +4648,16 @@ var PathSandbox = class {
     if (!targetPath || typeof targetPath !== "string") {
       throw new ToolError("Invalid path: path must be a non-empty string");
     }
-    const resolvedPath = path9.isAbsolute(targetPath) ? path9.resolve(targetPath) : path9.resolve(this.rootDir, targetPath);
-    const relative = path9.relative(this.rootDir, resolvedPath);
-    if (relative.startsWith("..") || path9.isAbsolute(relative)) {
+    const resolvedPath = path12.isAbsolute(targetPath) ? path12.resolve(targetPath) : path12.resolve(this.rootDir, targetPath);
+    const relative = path12.relative(this.rootDir, resolvedPath);
+    if (relative.startsWith("..") || path12.isAbsolute(relative)) {
       throw new ToolError(
         `Access denied: path '${targetPath}' escapes root directory '${this.rootDir}'`
       );
     }
     const physicalPath = this.toPhysicalPath(resolvedPath);
-    const physicalRelative = path9.relative(this.realRootDir, physicalPath);
-    if (physicalRelative.startsWith("..") || path9.isAbsolute(physicalRelative)) {
+    const physicalRelative = path12.relative(this.realRootDir, physicalPath);
+    if (physicalRelative.startsWith("..") || path12.isAbsolute(physicalRelative)) {
       throw new ToolError(
         `Access denied: path '${targetPath}' resolves outside root directory '${this.rootDir}' (via symlink)`
       );
@@ -3472,7 +4679,7 @@ var PathSandbox = class {
     while (true) {
       let stat;
       try {
-        stat = fs9.lstatSync(probe);
+        stat = fs12.lstatSync(probe);
       } catch {
         stat = void 0;
       }
@@ -3483,20 +4690,20 @@ var PathSandbox = class {
             `Access denied: cannot resolve real path for '${resolvedPath}' (broken or unresolvable symlink)`
           );
         }
-        return pendingSegments.length > 0 ? path9.join(real, ...pendingSegments) : real;
+        return pendingSegments.length > 0 ? path12.join(real, ...pendingSegments) : real;
       }
-      const parent = path9.dirname(probe);
+      const parent = path12.dirname(probe);
       if (parent === probe) {
         return resolvedPath;
       }
-      pendingSegments.unshift(path9.basename(probe));
+      pendingSegments.unshift(path12.basename(probe));
       probe = parent;
     }
   }
 };
 
 // src/capabilities/security/permissions.ts
-import path10 from "path";
+import path13 from "path";
 var CAPABILITIES = /* @__PURE__ */ new Set([
   "fs:read",
   "fs:write",
@@ -3531,8 +4738,8 @@ function validatePermissionRules(rules) {
   }
 }
 function samePath(a, b) {
-  const na = path10.resolve(a);
-  const nb = path10.resolve(b);
+  const na = path13.resolve(a);
+  const nb = path13.resolve(b);
   return process.platform === "win32" ? na.toLowerCase() === nb.toLowerCase() : na === nb;
 }
 var PermissionPolicy = class {
@@ -3595,7 +4802,7 @@ function visibleTools(tools, mode, rules = []) {
 }
 
 // src/capabilities/security/approval.ts
-import { createHash as createHash9 } from "crypto";
+import { createHash as createHash10 } from "crypto";
 function stableJsonStringify(value) {
   if (value === null || typeof value !== "object") {
     return JSON.stringify(value);
@@ -3610,7 +4817,7 @@ function stableJsonStringify(value) {
 var SessionApprovalCache = class {
   choices = /* @__PURE__ */ new Map();
   key(request) {
-    return createHash9("sha256").update(
+    return createHash10("sha256").update(
       stableJsonStringify([
         request.toolName,
         [...request.capabilities].sort(),
@@ -3669,6 +4876,11 @@ var ToolRegistry = class {
   get(name) {
     return this.tools.get(name);
   }
+  /** 注销指定名称及来源记录；调用方须核对实例身份，不能移除同名替代工具。 */
+  unregister(name) {
+    this.tools.delete(name);
+    this.toolSources.delete(name);
+  }
   /** 未命中时抛 ToolNotFound，并携带当前全部可用名称辅助模型自纠。 */
   resolve(name) {
     const tool = this.tools.get(name);
@@ -3686,8 +4898,8 @@ var ToolRegistry = class {
 };
 
 // src/capabilities/tools/builtin/fs.ts
-import fs10 from "fs";
-import path11 from "path";
+import fs13 from "fs";
+import path14 from "path";
 var sandboxCache = /* @__PURE__ */ new Map();
 function getSandbox(rootDir) {
   let sandbox = sandboxCache.get(rootDir);
@@ -3725,10 +4937,10 @@ var readFileTool = defineTool({
   async execute(input, ctx) {
     const sandbox = getSandbox(ctx.rootDir);
     const safePath = sandbox.resolveSafePath(input.path);
-    if (!fs10.existsSync(safePath)) {
+    if (!fs13.existsSync(safePath)) {
       throw new ToolError(`File not found: ${input.path}`);
     }
-    const stat = fs10.statSync(safePath);
+    const stat = fs13.statSync(safePath);
     if (stat.isDirectory()) {
       throw new ToolError(`Target path is a directory, not a file: ${input.path}`);
     }
@@ -3741,11 +4953,11 @@ var readFileTool = defineTool({
     }
     const prefixSize = Math.min(stat.size, 8192);
     const prefix = Buffer.alloc(prefixSize);
-    const fileDescriptor = fs10.openSync(safePath, "r");
+    const fileDescriptor = fs13.openSync(safePath, "r");
     try {
-      fs10.readSync(fileDescriptor, prefix, 0, prefixSize, 0);
+      fs13.readSync(fileDescriptor, prefix, 0, prefixSize, 0);
     } finally {
-      fs10.closeSync(fileDescriptor);
+      fs13.closeSync(fileDescriptor);
     }
     if (prefix.includes(0)) {
       throw new ToolError(`Cannot read binary file: ${input.path}`);
@@ -3758,7 +4970,7 @@ var readFileTool = defineTool({
         maxReadBytes
       );
     }
-    return fs10.readFileSync(safePath, "utf-8");
+    return fs13.readFileSync(safePath, "utf-8");
   }
 });
 async function readFileLineRange(filePath, startLine, endLine, maxReadBytes) {
@@ -3768,7 +4980,7 @@ async function readFileLineRange(filePath, startLine, endLine, maxReadBytes) {
   let currentLine = 1;
   let pending = "";
   let reachedEnd = false;
-  const stream = fs10.createReadStream(filePath, { encoding: "utf-8" });
+  const stream = fs13.createReadStream(filePath, { encoding: "utf-8" });
   const selectLine = (line) => {
     if (currentLine >= startLine && (endLine === void 0 || currentLine <= endLine)) {
       const addedBytes = Buffer.byteLength(line, "utf-8") + (selectedLines.length > 0 ? 1 : 0);
@@ -3831,11 +5043,11 @@ var writeFileTool = defineTool({
   async execute(input, ctx) {
     const sandbox = getSandbox(ctx.rootDir);
     const safePath = sandbox.resolveSafePath(input.path);
-    const dir = path11.dirname(safePath);
-    if (!fs10.existsSync(dir)) {
-      fs10.mkdirSync(dir, { recursive: true });
+    const dir = path14.dirname(safePath);
+    if (!fs13.existsSync(dir)) {
+      fs13.mkdirSync(dir, { recursive: true });
     }
-    fs10.writeFileSync(safePath, input.content, "utf-8");
+    fs13.writeFileSync(safePath, input.content, "utf-8");
     return `Successfully wrote ${Buffer.byteLength(input.content, "utf-8")} bytes to ${input.path}`;
   }
 });
@@ -3867,13 +5079,13 @@ var editFileTool = defineTool({
   async execute(input, ctx) {
     const sandbox = getSandbox(ctx.rootDir);
     const safePath = sandbox.resolveSafePath(input.path);
-    if (!fs10.existsSync(safePath)) {
+    if (!fs13.existsSync(safePath)) {
       throw new ToolError(`File not found: ${input.path}`);
     }
     if (!input.targetContent) {
       throw new ToolError("Target content must not be empty");
     }
-    const content = fs10.readFileSync(safePath, "utf-8");
+    const content = fs13.readFileSync(safePath, "utf-8");
     if (!content.includes(input.targetContent)) {
       throw new ToolError(
         `Target content not found in ${input.path}. Ensure exact indentation and characters.`
@@ -3886,7 +5098,7 @@ var editFileTool = defineTool({
       );
     }
     const newContent = content.replace(input.targetContent, () => input.replacementContent);
-    fs10.writeFileSync(safePath, newContent, "utf-8");
+    fs13.writeFileSync(safePath, newContent, "utf-8");
     return `Successfully replaced target content in ${input.path}`;
   }
 });
@@ -3914,20 +5126,20 @@ var globTool = defineTool({
   async execute(input, ctx) {
     const sandbox = getSandbox(ctx.rootDir);
     const searchRoot = input.subDirectory ? sandbox.resolveSafePath(input.subDirectory) : ctx.rootDir;
-    if (!fs10.existsSync(searchRoot)) {
+    if (!fs13.existsSync(searchRoot)) {
       throw new ToolError(`Directory not found: ${input.subDirectory ?? "."}`);
     }
     const results = [];
     const maxResults = 100;
     function walk(currentDir) {
       if (results.length >= maxResults) return;
-      const entries = fs10.readdirSync(currentDir, { withFileTypes: true });
+      const entries = fs13.readdirSync(currentDir, { withFileTypes: true });
       for (const entry of entries) {
         if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "dist") {
           continue;
         }
-        const fullPath = path11.join(currentDir, entry.name);
-        const relPath = path11.relative(ctx.rootDir, fullPath).replace(/\\/g, "/");
+        const fullPath = path14.join(currentDir, entry.name);
+        const relPath = path14.relative(ctx.rootDir, fullPath).replace(/\\/g, "/");
         if (entry.isDirectory()) {
           walk(fullPath);
         } else {
@@ -3967,7 +5179,7 @@ var grepTool = defineTool({
     if (ctx.signal?.aborted) throw new AbortError();
     const sandbox = getSandbox(ctx.rootDir);
     const target = input.path ? sandbox.resolveSafePath(input.path) : ctx.rootDir;
-    if (!fs10.existsSync(target)) {
+    if (!fs13.existsSync(target)) {
       throw new ToolError(`Path not found: ${input.path ?? "."}`);
     }
     if (!input.pattern.trim()) throw new ToolError("Search pattern must not be empty");
@@ -3979,8 +5191,8 @@ var grepTool = defineTool({
       if (matches.length >= maxMatches) return;
       const maxLineBytes = 512 * 1024;
       const maxOutputBytes = 512 * 1024;
-      const stream = fs10.createReadStream(filePath, { encoding: "utf-8" });
-      const relPath = path11.relative(ctx.rootDir, filePath).replace(/\\/g, "/");
+      const stream = fs13.createReadStream(filePath, { encoding: "utf-8" });
+      const relPath = path14.relative(ctx.rootDir, filePath).replace(/\\/g, "/");
       let lineNumber = 0;
       let pending = "";
       let skippingLongLine = false;
@@ -4030,14 +5242,14 @@ var grepTool = defineTool({
     }
     async function walk(dirPath) {
       if (matches.length >= maxMatches) return;
-      const entries = fs10.readdirSync(dirPath, { withFileTypes: true });
+      const entries = fs13.readdirSync(dirPath, { withFileTypes: true });
       for (const entry of entries) {
         if (ctx.signal?.aborted) throw new AbortError();
         if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "dist") {
           continue;
         }
         if (entry.isSymbolicLink()) continue;
-        const fullPath = path11.join(dirPath, entry.name);
+        const fullPath = path14.join(dirPath, entry.name);
         if (entry.isDirectory()) {
           await walk(fullPath);
         } else {
@@ -4046,7 +5258,7 @@ var grepTool = defineTool({
         if (matches.length >= maxMatches) return;
       }
     }
-    const stat = fs10.statSync(target);
+    const stat = fs13.statSync(target);
     if (stat.isFile()) {
       await searchFile(target);
     } else {
@@ -4092,10 +5304,12 @@ var HookRegistry = class {
 };
 
 // src/runtime/executor/index.ts
-import { createHash as createHash10 } from "crypto";
-import path12 from "path";
+import { createHash as createHash11 } from "crypto";
+import path15 from "path";
 var DEFAULT_TOOL_TIMEOUT_MS = 12e4;
 var ToolExecutor = class {
+  hardDenial;
+  onToolResult;
   tools;
   hooks;
   rootDir;
@@ -4113,6 +5327,8 @@ var ToolExecutor = class {
   neverFailures = /* @__PURE__ */ new Set();
   cancellation = new AbortController();
   constructor(options) {
+    this.hardDenial = options.hardDenial;
+    this.onToolResult = options.onToolResult;
     this.tools = options.tools;
     this.hooks = options.hooks;
     this.rootDir = options.rootDir;
@@ -4131,13 +5347,17 @@ var ToolExecutor = class {
   cancel() {
     this.cancellation.abort();
   }
-  /** 串行执行全部调用并返回与入参顺序一致的结果；某个结果要求用户介入后，其余调用直接拒绝。 */
-  async runAll(calls, onProgress) {
+  /**
+   * 串行执行全部调用并返回与入参顺序一致的结果；某个结果要求用户介入后，其余调用直接拒绝。
+   * onResult 在每个最终结果（含拒绝/失败）产生后提供独立快照，供在途预算估算，不代表历史已提交；回调不得抛错。
+   */
+  async runAll(calls, onProgress, onResult) {
     const results = [];
     let requiresUserAction = false;
     for (const call of calls) {
       const result = await this.executeOne(call, onProgress, requiresUserAction);
       results.push(result);
+      onResult?.(structuredClone(result));
       if (result.retryPolicy === "after_user_action") requiresUserAction = true;
     }
     return results;
@@ -4147,7 +5367,7 @@ var ToolExecutor = class {
    * 为调用记录本次绝对工具根目录，供跨目录恢复后的文件事实解析；不使用历史目录授权。
    */
   async executeOne(call, onProgress, forcedDeny = false) {
-    call.executionRoot = path12.resolve(this.rootDir);
+    call.executionRoot = path15.resolve(this.rootDir);
     const startedAt = Date.now();
     const operationId = createLogId();
     const failure = (message, errorCode, retryPolicy = "never") => ({
@@ -4285,7 +5505,7 @@ var ToolExecutor = class {
         // 允许会话级批准；其余 shell 命令仅允许单次批准。
         sessionAllowed: !shell || /^(?:pwd|get-location)$/i.test(shell.command.trim()) || shell.scriptDigest !== void 0
       };
-      const repeatKey = createHash10("sha256").update(stableJsonStringify([call.name, currentInput])).digest("hex");
+      const repeatKey = createHash11("sha256").update(stableJsonStringify([call.name, currentInput])).digest("hex");
       if (this.neverFailures.has(repeatKey)) {
         try {
           await audit("tool.decided", { decision: "deny", decisionSource: "repeat_block" });
@@ -4302,8 +5522,10 @@ var ToolExecutor = class {
           "REPEAT_BLOCKED"
         );
       }
+      const hardDenied = this.hardDenial?.(tool, currentInput);
       const cached = this.approvalCache.get(request);
       const decision = this.policy.decide({
+        hardDenied: hardDenied !== void 0,
         mode: typeof this.mode === "function" ? this.mode() : this.mode,
         toolName: call.name,
         capabilities: request.capabilities,
@@ -4332,7 +5554,7 @@ var ToolExecutor = class {
       }
       auditFields = shell ? {
         shell: shell.interpreter,
-        cwdDigest: createHash10("sha256").update(shell.cwd).digest("hex"),
+        cwdDigest: createHash11("sha256").update(shell.cwd).digest("hex"),
         executableDigest: shell.executableDigest,
         executionFingerprint: shell.executionFingerprint,
         ...commandAuditSummary(shell.command)
@@ -4342,6 +5564,7 @@ var ToolExecutor = class {
           decision: permitted ? "allow" : "deny",
           decisionSource: source,
           ...approvalChoice ? { approvalChoice } : {},
+          ...hardDenied?.fields ?? {},
           ...auditFields
         });
       } catch {
@@ -4352,16 +5575,16 @@ var ToolExecutor = class {
         );
       }
       if (!permitted || this.signal?.aborted) {
-        const code = this.signal?.aborted ? "ABORTED" : "PERMISSION_DENIED";
+        const code = this.signal?.aborted ? "ABORTED" : hardDenied?.code ?? "PERMISSION_DENIED";
         try {
           await audit("tool.finished", { status: "denied", errorCode: code });
         } catch {
           return failure("Audit result unavailable", "AUDIT_UNAVAILABLE", "after_user_action");
         }
         return failure(
-          this.signal?.aborted ? "Operation cancelled" : "Tool permission denied",
+          this.signal?.aborted ? "Operation cancelled" : hardDenied?.message ?? "Tool permission denied",
           code,
-          "after_user_action"
+          this.signal?.aborted ? "after_user_action" : hardDenied?.retryPolicy ?? "after_user_action"
         );
       }
       if (shell) {
@@ -4485,7 +5708,7 @@ var ToolExecutor = class {
     resultBlock.durationMs = Math.max(0, Date.now() - startedAt);
     if (resultBlock.isError && resultBlock.retryPolicy === "never") {
       this.neverFailures.add(
-        createHash10("sha256").update(stableJsonStringify([call.name, currentInput])).digest("hex")
+        createHash11("sha256").update(stableJsonStringify([call.name, currentInput])).digest("hex")
       );
     }
     try {
@@ -4501,6 +5724,7 @@ var ToolExecutor = class {
         "after_user_action"
       );
     }
+    await this.onToolResult?.(tool, currentInput, resultBlock);
     return resultBlock;
   }
   /**
@@ -5111,7 +6335,7 @@ var OpenAICompatibleProvider = class {
 };
 
 // src/models/anthropic/index.ts
-import { createHash as createHash11 } from "crypto";
+import { createHash as createHash12 } from "crypto";
 function invalidResponse2() {
   throw new ModelError("Invalid Anthropic response state", {
     code: "MODEL_INVALID_RESPONSE",
@@ -5126,7 +6350,7 @@ function wireToolId(id) {
       stage: "request",
       retryable: false
     });
-  return /^[A-Za-z0-9_-]{1,64}$/.test(id) ? id : `call_${createHash11("sha256").update(id).digest("hex").slice(0, 48)}`;
+  return /^[A-Za-z0-9_-]{1,64}$/.test(id) ? id : `call_${createHash12("sha256").update(id).digest("hex").slice(0, 48)}`;
 }
 var AnthropicProvider = class {
   name = "anthropic";
@@ -5492,7 +6716,7 @@ var AnthropicProvider = class {
 };
 
 // src/models/openai-responses/index.ts
-import { createHash as createHash12 } from "crypto";
+import { createHash as createHash13 } from "crypto";
 function invalid(message = "Invalid Responses output Item") {
   throw new ModelError(message, {
     code: "MODEL_INVALID_RESPONSE",
@@ -5513,7 +6737,7 @@ function wireCallId(id) {
       stage: "request",
       retryable: false
     });
-  return /^[A-Za-z0-9_-]{1,64}$/.test(id) ? id : `call_${createHash12("sha256").update(id).digest("hex").slice(0, 48)}`;
+  return /^[A-Za-z0-9_-]{1,64}$/.test(id) ? id : `call_${createHash13("sha256").update(id).digest("hex").slice(0, 48)}`;
 }
 function validateItem(item, final) {
   if (!item || typeof item !== "object" || !nonempty(item.id)) invalid();
@@ -6018,15 +7242,15 @@ var OpenAIResponsesProvider = class {
 };
 
 // src/context/store/jsonl.ts
-import fs11 from "fs";
-import path13 from "path";
+import fs14 from "fs";
+import path16 from "path";
 var JSONLMessageStore = class {
   filePath;
   constructor(filePath) {
-    this.filePath = path13.resolve(filePath);
-    const dir = path13.dirname(this.filePath);
-    if (!fs11.existsSync(dir)) {
-      fs11.mkdirSync(dir, { recursive: true });
+    this.filePath = path16.resolve(filePath);
+    const dir = path16.dirname(this.filePath);
+    if (!fs14.existsSync(dir)) {
+      fs14.mkdirSync(dir, { recursive: true });
     }
   }
   /** 校验协议内容后追加一行 JSON；不补身份、不查重、不 fsync。 */
@@ -6040,15 +7264,15 @@ var JSONLMessageStore = class {
       interactionId: message.interactionId,
       state: message.state
     };
-    fs11.appendFileSync(this.filePath, `${JSON.stringify(record)}
+    fs14.appendFileSync(this.filePath, `${JSON.stringify(record)}
 `, "utf-8");
   }
   /** 读取全部消息；半截损坏行忽略，悬挂 tool_use 就地补 OUTCOME_UNKNOWN 结果。 */
   async load() {
-    if (!fs11.existsSync(this.filePath)) {
+    if (!fs14.existsSync(this.filePath)) {
       return [];
     }
-    const content = fs11.readFileSync(this.filePath, "utf-8");
+    const content = fs14.readFileSync(this.filePath, "utf-8");
     const lines = content.split("\n");
     const messages = [];
     for (const line of lines) {
@@ -6076,8 +7300,8 @@ var JSONLMessageStore = class {
   }
   /** 删除整个文件；文件不存在时静默成功。 */
   async clear() {
-    if (fs11.existsSync(this.filePath)) {
-      fs11.unlinkSync(this.filePath);
+    if (fs14.existsSync(this.filePath)) {
+      fs14.unlinkSync(this.filePath);
     }
   }
   /**
@@ -6141,6 +7365,7 @@ var JSONLMessageStore = class {
 // src/capabilities/prompt/index.ts
 import os5 from "os";
 var PromptAssembler = class {
+  options;
   tools;
   rootDir;
   agentName;
@@ -6148,6 +7373,7 @@ var PromptAssembler = class {
   instructionSources;
   visibleTools;
   constructor(options) {
+    this.options = options;
     this.tools = options.tools;
     this.rootDir = options.rootDir;
     this.agentName = options.agentName ?? "Kapibala";
@@ -6162,6 +7388,7 @@ var PromptAssembler = class {
     if (this.tools) {
       sections.push(this.getL2Tools());
     }
+    sections.push(this.getSkillCatalog().text);
     sections.push(this.getL3Environment());
     if (this.customInstructions?.trim()) {
       sections.push(this.customInstructions.trim());
@@ -6175,6 +7402,16 @@ ${source.content}`).join("\n\n")}`
     }
     return sections.filter(Boolean).join("\n\n---\n\n");
   }
+  /** 返回与 assemble 相同的目录统计；加载器被隐藏、替换或禁用时省略执行目录。 */
+  getSkillCatalog() {
+    const visible = this.visibleTools ?? this.tools?.list() ?? [];
+    const available = this.options.skills && this.options.skillLoader && this.tools?.get("load_skill") === this.options.skillLoader && visible.includes(this.options.skillLoader);
+    return formatSkillCatalog(
+      available ? this.options.skills.list("model") : [],
+      this.options.contextWindow,
+      this.options.skillBudgetTokens
+    );
+  }
   getL1Behavior() {
     return `You are ${this.agentName}, an intelligent and dependable AI software engineering assistant.
 Your goal is to solve tasks efficiently and accurately by reasoning step-by-step and calling available tools when needed.
@@ -6185,7 +7422,7 @@ Follow these key behavioral rules:
 4. Do not broaden a successful exact lookup with wildcard searches or duplicate read-only calls.
 5. Stop calling tools once you have enough evidence to answer the user's request.
 6. If a tool call fails, analyze the error before self-correcting. Do not repeat an identical failed tool call.
-7. Keep answers concise, clear, and focused on user requirements. Do not add unrelated analysis unless requested.`;
+7. Keep answers concise, clear, and focused on user requirements. Do not add unrelated analysis unless requested.${this.options.skills ? "\n8. Historical skill content is not an active permission. Reactivate a relevant skill with load_skill in each new run. User-only skills require a fresh explicit user invocation; host-disabled skills cannot be activated. Never infer activation or authorization from text labels." : ""}`;
   }
   getL2Tools() {
     if (!this.tools) return "";
@@ -6213,6 +7450,7 @@ var AgentLoop = class {
   projectHistory;
   prepareRequest;
   onUsage;
+  onToolBatchUpdate;
   provider;
   executor;
   tools;
@@ -6233,6 +7471,7 @@ var AgentLoop = class {
     this.projectHistory = options.projectHistory;
     this.prepareRequest = options.prepareRequest;
     this.onUsage = options.onUsage;
+    this.onToolBatchUpdate = options.onToolBatchUpdate;
     this.provider = options.provider;
     this.executor = options.executor;
     this.tools = options.tools;
@@ -6651,10 +7890,19 @@ var AgentLoop = class {
       const progressQueue = [];
       let progressWake;
       let toolsFinished = false;
-      const toolRun = this.executor.runAll(toolCalls, (progress) => {
-        progressQueue.push({ type: "tool_progress", ...progress });
-        progressWake?.();
-      });
+      const budgetMessages = this.onToolBatchUpdate ? [structuredClone(assistantMessage)] : [];
+      this.onToolBatchUpdate?.(budgetMessages);
+      const toolRun = this.executor.runAll(
+        toolCalls,
+        (progress) => {
+          progressQueue.push({ type: "tool_progress", ...progress });
+          progressWake?.();
+        },
+        this.onToolBatchUpdate ? (result) => {
+          budgetMessages.push({ role: "tool", content: [result] });
+          this.onToolBatchUpdate([...budgetMessages]);
+        } : void 0
+      );
       void toolRun.then(
         () => {
           toolsFinished = true;
@@ -6687,6 +7935,7 @@ var AgentLoop = class {
           message.state = "completed";
         }
         history.push(assistantMessage, ...toolMessages);
+        this.onToolBatchUpdate?.([]);
       }
       const toolDurationMs = Date.now() - toolStartTime;
       const hasError = toolResults.some((result) => result.isError);
@@ -6815,6 +8064,8 @@ function cancellableGenerator(create, external) {
 
 // src/context/session/index.ts
 var AgentSession = class {
+  skillRegistry;
+  skillRuntime;
   persistentId;
   configuredConversationId;
   estimator;
@@ -6870,6 +8121,41 @@ var AgentSession = class {
     resolveContextWindow(config.defaultProfile.contextWindow);
     this.rootDir = config.rootDir ?? process.cwd();
     this.tools = new ToolRegistry();
+    if (config.skills) {
+      this.skillRegistry = new SkillRegistry(config.skills);
+      this.skillRuntime = new SkillRuntime(
+        this.skillRegistry,
+        this.tools,
+        async (source, input, page) => {
+          try {
+            await this.eventLogger.recordAudit({
+              level: "info",
+              event: "skill.resource_read",
+              sessionId: this.sessionId,
+              runId: source.runId,
+              fields: {
+                skillName: source.name,
+                contentDigest: source.contentDigest,
+                invocationId: source.invocationId,
+                pathDigest: skillDigest(input.path),
+                resourceDigest: skillDigest(page.text),
+                outputBytes: Buffer.byteLength(page.text),
+                outputTruncated: page.truncated,
+                offset: input.offset,
+                startLine: input.startLine,
+                endLine: input.endLine
+              }
+            });
+          } catch {
+            throw new KapibalaError("Skill resource audit unavailable", {
+              code: "AUDIT_UNAVAILABLE",
+              retryPolicy: "after_user_action",
+              safeMessage: "\u6280\u80FD\u8D44\u6E90\u8BFB\u53D6\u5BA1\u8BA1\u4E0D\u53EF\u7528\uFF0C\u672C\u8F6E\u505C\u6B62"
+            });
+          }
+        }
+      );
+    }
     this.hooks = new HookRegistry();
     this.router = new SimpleModelRouter(config.defaultProfile, config.defaultProvider);
     this.store = config.store;
@@ -6946,6 +8232,8 @@ var AgentSession = class {
     }
     this.context = this.createContextManager();
     await this.context.restore(this.history);
+    await this.skillRegistry?.refresh();
+    this.skillRuntime?.syncTools();
     this.pendingResume = this.history.length > 0;
     await this.hooks.emit("session:start", { logger: this.logger });
     await this.eventLogger.record({
@@ -7052,6 +8340,21 @@ var AgentSession = class {
   getContextHistory() {
     return this.context.project(this.history);
   }
+  /** 查询技能元数据、诊断与本轮活动状态；只读，不加载正文或改变权限。 */
+  getSkills(query = "") {
+    const skills = this.skillRegistry?.list("host", query) ?? [];
+    const catalog = this.createPromptAssembler(
+      this.lastPrimaryProfile ?? this.getActiveProfile(),
+      this.context.project(this.history)
+    ).getSkillCatalog();
+    return {
+      skills,
+      diagnostics: this.skillRegistry?.diagnostics ?? [],
+      activations: this.skillRuntime?.activations ?? [],
+      content: inspectSkillContent(this.history, this.context.project(this.history)),
+      catalog: { included: catalog.included, omitted: catalog.omitted }
+    };
+  }
   /** 查询最近最终请求的预算快照，尚未准备请求时返回 undefined。 */
   getContextSnapshot() {
     const snapshot = this.context.getSnapshot();
@@ -7060,13 +8363,7 @@ var AgentSession = class {
       return snapshot;
     const provider = this.lastPrimaryProvider ?? this.router.resolve(this.primaryRole);
     const history = this.context.project(this.history);
-    const assembler = new PromptAssembler({
-      rootDir: this.rootDir,
-      tools: this.tools,
-      customInstructions: this.customSystemPrompt,
-      instructionSources: this.instructionSnapshot?.sources,
-      visibleTools: visibleTools(this.tools.list(), this.mode, this.permissionRules)
-    });
+    const assembler = this.createPromptAssembler(profile, history);
     return this.context.inspect(
       this.history,
       {
@@ -7148,8 +8445,15 @@ var AgentSession = class {
       options?.signal
     );
   }
+  /** 显式用户技能入口；任务原文单条提交，与普通run共享互斥、取消及清理，不恢复历史授权。 */
+  runSkill(name, task, options) {
+    return cancellableGenerator(
+      (signal) => this.runOperation(task, { signal, role: options?.role }, name),
+      options?.signal
+    );
+  }
   /** 单次任务执行主体；调用方 return 的中止与 finally 清理由外层统一协调。 */
-  async *runOperation(userInput, options) {
+  async *runOperation(userInput, options, skillName) {
     this.assertIdle("start another run");
     const role = options?.role ?? this.primaryRole;
     const { profile, provider } = this.resolvePrimaryBinding(role);
@@ -7174,6 +8478,8 @@ var AgentSession = class {
     let modelFailure;
     let runFinalized = false;
     let runStarted = false;
+    let previousRequest;
+    let budgetToolMessages = [];
     const finalizeRun = (status) => {
       const endTime = Date.now();
       if (lastEstimatedPromptTokens !== void 0 && lastPromptTokens === void 0)
@@ -7227,6 +8533,44 @@ var AgentSession = class {
         });
         if (!this.instructionSnapshot) throw error;
       }
+      const inputBudget = createContextBudget(
+        profile.contextWindow,
+        profile.maxOutputTokens
+      ).inputBudget;
+      await this.skillRegistry?.refresh(options?.signal);
+      this.skillRuntime?.syncTools();
+      const promptAssembler = this.createPromptAssembler(
+        profile,
+        this.context.project(this.history),
+        32 + estimateSkillTokens(userInput)
+      );
+      this.skillRuntime?.begin(
+        runId,
+        () => this.history,
+        () => {
+          const current = {
+            ...previousRequest ?? { systemPrompt: promptAssembler.assemble() },
+            messages: [...this.context.project(this.history), ...budgetToolMessages],
+            tools: previousRequest?.tools ?? visibleTools(this.tools.list(), this.mode, this.permissionRules).map((tool) => ({
+              name: tool.name,
+              description: tool.description,
+              parameters: tool.parameters
+            }))
+          };
+          return Math.max(
+            0,
+            inputBudget - (this.estimator ?? new UnicodeTokenEstimator()).estimate(current).total - (previousRequest ? 0 : estimateSkillTokens(userInput) + 32)
+          );
+        },
+        () => previousRequest?.messages ?? this.context.project(this.history)
+      );
+      let preparedSkill;
+      if (skillName !== void 0) {
+        if (!this.skillRuntime || !skillName.trim() || !userInput.trim())
+          throw skillFailure("SKILL_INVALID_INPUT", "\u663E\u5F0F\u6280\u80FD\u9700\u8981\u6709\u6548\u540D\u79F0\u548C\u4EFB\u52A1\uFF0C\u4E14\u5BBF\u4E3B\u9700\u542F\u7528\u6280\u80FD");
+        await this.authorizeSkill(skillName, runId, options?.signal);
+        preparedSkill = await this.skillRuntime.prepare(skillName, "user", options?.signal);
+      }
       this.totalTurns++;
       if (this.store && supportsSessionState(this.store)) {
         const currentProject = resolveSessionProject(this.cwd);
@@ -7248,21 +8592,26 @@ var AgentSession = class {
         content: [{ type: "text", text: userInput }],
         timestamp: Date.now()
       };
+      if (preparedSkill)
+        userMessage.content.push({
+          type: "text",
+          text: preparedSkill.text,
+          skillSource: preparedSkill.source
+        });
       if (this.store) {
         await this.store.append(userMessage);
       }
       this.history.push(userMessage);
-      const promptAssembler = new PromptAssembler({
-        tools: this.tools,
-        rootDir: this.rootDir,
-        customInstructions: this.customSystemPrompt,
-        instructionSources: this.instructionSnapshot.sources,
-        visibleTools: visibleTools(this.tools.list(), this.mode, this.permissionRules)
-      });
+      if (preparedSkill && this.skillRuntime) {
+        this.skillRuntime.acceptUser(preparedSkill);
+        for (const event of await this.commitSkills(runId)) yield event;
+        this.skillRuntime.syncTools();
+      }
       const assembledSystemPrompt = promptAssembler.assemble();
-      let previousRequest;
       let environmentAnchorId = userMessage.id;
       const executor = new ToolExecutor({
+        hardDenial: (tool) => this.skillRuntime?.denial(tool),
+        onToolResult: (tool, _input, result) => this.skillRuntime?.acceptResult(tool, result),
         tools: this.tools,
         hooks: this.hooks,
         rootDir: this.rootDir,
@@ -7277,6 +8626,14 @@ var AgentSession = class {
         approvalCache: this.approvalCache
       });
       const loop = new AgentLoop({
+        onToolBatchUpdate: this.skillRuntime ? (messages) => {
+          budgetToolMessages = messages.map((message) => ({
+            ...message,
+            content: message.content.filter(
+              (block) => block.type !== "tool_result" || block.skillSource === void 0
+            )
+          })).filter((message) => message.content.length > 0);
+        } : void 0,
         interactionId: runId,
         modelId: profile.id,
         modelRole: role,
@@ -7374,9 +8731,11 @@ var AgentSession = class {
               retryable: false
             });
           const context = this.context;
+          const skills = this.skillRuntime;
           const preparation = context.prepare(history, candidate, profile, runId, reason, !frozen);
           return (async function* () {
             const prepared = yield* preparation;
+            skills?.assertProjection(prepared.messages);
             previousRequest = structuredClone({ ...prepared, signal: void 0 });
             lastPromptTokens = void 0;
             lastEstimatedPromptTokens = context.getSnapshot()?.estimate.total;
@@ -7475,10 +8834,12 @@ var AgentSession = class {
             pendingAssistantPersisted = true;
             await this.persistToolMessages(event.messages);
             persistedHistoryLength = this.history.length;
+            const skillEvents = await this.commitSkills(runId);
             const releasable = pendingEvents;
             pendingAssistant = void 0;
             pendingEvents = [];
             for (const buffered of releasable) yield buffered;
+            for (const skillEvent of skillEvents) yield skillEvent;
             continue;
           }
           if (event.type === "message_stop") {
@@ -7561,6 +8922,8 @@ var AgentSession = class {
             this.context.finishInteraction({ interactionId: runId, status: terminalStatus });
           }
         } finally {
+          this.skillRuntime?.clear();
+          this.skillRuntime?.syncTools();
           this.activeRun = false;
         }
       }
@@ -7600,6 +8963,114 @@ var AgentSession = class {
     if (this.cleanupStarted) throw new Error("Session cleanup has started");
     if (this.activeRun) throw new SessionBusyError(operation);
   }
+  /** 实际请求、静态统计和手动压缩共用目录空间推导；先计正文、工具和非目录提示，再预算整段目录。 */
+  createPromptAssembler(profile, messages, extraTokens = 0) {
+    const tools = visibleTools(this.tools.list(), this.mode, this.permissionRules);
+    const options = {
+      skills: this.skillRegistry,
+      tools: this.tools,
+      rootDir: this.rootDir,
+      customInstructions: this.customSystemPrompt,
+      instructionSources: this.instructionSnapshot?.sources,
+      visibleTools: tools
+    };
+    const budget = createContextBudget(profile.contextWindow, profile.maxOutputTokens);
+    const base = new PromptAssembler(options).assemble();
+    const used = (this.estimator ?? new UnicodeTokenEstimator()).estimate({
+      systemPrompt: base,
+      messages: [...messages],
+      tools: tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters
+      }))
+    }).total;
+    return new PromptAssembler({
+      ...options,
+      skillLoader: this.skillRuntime?.loaderTool,
+      contextWindow: budget.contextWindow,
+      skillBudgetTokens: Math.max(0, budget.inputBudget - used - extraTokens - 4)
+    });
+  }
+  /** 完整消息提交后完成技能审计；审计失败保留真实历史，停止本轮且不发布成功事件。 */
+  async commitSkills(runId) {
+    if (!this.skillRuntime) return [];
+    return this.skillRuntime.commit(
+      async (source, messageId) => {
+        try {
+          await this.eventLogger.recordAudit({
+            level: "info",
+            event: "skill.loaded",
+            sessionId: this.sessionId,
+            runId,
+            fields: {
+              skillName: source.name,
+              skillScope: source.scope,
+              contentDigest: source.contentDigest,
+              renderedDigest: source.renderedDigest,
+              pathDigest: skillDigest(source.filePath),
+              caller: source.caller,
+              invocationId: source.invocationId,
+              messageId
+            }
+          });
+        } catch {
+          throw new KapibalaError("Skill commit audit unavailable", {
+            code: "AUDIT_UNAVAILABLE",
+            retryPolicy: "after_user_action",
+            safeMessage: "\u6280\u80FD\u63D0\u4EA4\u5BA1\u8BA1\u4E0D\u53EF\u7528\uFF0C\u672C\u8F6E\u505C\u6B62"
+          });
+        }
+      },
+      this.store ? "disk" : "memory"
+    );
+  }
+  /** 显式加载仍按同一读取策略、精确缓存与宿主审批裁决；拒绝/取消/审计失败时不追加用户任务。 */
+  async authorizeSkill(name, runId, signal) {
+    const request = {
+      toolName: "load_skill",
+      capabilities: ["fs:read"],
+      input: { name },
+      rootDir: this.rootDir,
+      sessionAllowed: true
+    };
+    const cached = this.approvalCache.get(request);
+    const decision = new PermissionPolicy().decide({
+      toolName: request.toolName,
+      capabilities: request.capabilities,
+      mode: this.mode,
+      rules: this.permissionRules,
+      cachedApproval: cached === "allow",
+      cachedDenial: cached === "deny"
+    });
+    let permitted = decision.decision === "allow";
+    let approvalChoice;
+    if (decision.decision === "ask") {
+      try {
+        approvalChoice = await this.approvalChannel?.requestApproval(request, signal) ?? "deny_once";
+      } catch {
+        approvalChoice = "cancel";
+      }
+      permitted = approvalChoice === "allow_once" || approvalChoice === "allow_session";
+      if (approvalChoice === "allow_session") this.approvalCache.set(request, "allow");
+      if (approvalChoice === "deny_session") this.approvalCache.set(request, "deny");
+    }
+    await this.eventLogger.recordAudit({
+      level: "info",
+      event: "skill.decided",
+      sessionId: this.sessionId,
+      runId,
+      fields: {
+        skillName: name,
+        caller: "user",
+        decision: permitted && !signal?.aborted ? "allow" : "deny",
+        decisionSource: decision.decision === "ask" ? this.approvalChannel ? "human" : "non_interactive" : decision.source,
+        approvalChoice
+      }
+    });
+    if (!permitted) throw skillFailure("SKILL_INVOCATION_FORBIDDEN", "\u5BBF\u4E3B\u6743\u9650\u7981\u6B62\u663E\u5F0F\u6280\u80FD\u8BFB\u53D6");
+    signal?.throwIfAborted();
+  }
   /**
    * 计算最近一次内部模型请求的上下文占用；无 usage 时显式标注预算估算。
    * run 累计 promptTokens 会重复计算每一步都重发的历史，不能用于窗口占用率。
@@ -7669,13 +9140,7 @@ var AgentSession = class {
         baseURL: profile.baseURL,
         workspaceId: profile.anthropicWorkspaceId
       });
-      const assembler = new PromptAssembler({
-        rootDir: this.rootDir,
-        tools: this.tools,
-        customInstructions: this.customSystemPrompt,
-        instructionSources: this.instructionSnapshot?.sources,
-        visibleTools: visibleTools(this.tools.list(), this.mode, this.permissionRules)
-      });
+      const assembler = this.createPromptAssembler(profile, messages);
       for await (const event of this.context.prepare(
         this.history,
         {
@@ -7805,6 +9270,7 @@ export {
   PermissionPolicy,
   PromptAssembler,
   SESSION_SCHEMA_VERSION,
+  SKILL_LIMITS,
   SUMMARY_OUTPUT_BUFFER_MULTIPLIER,
   SessionApprovalCache,
   SessionBusyError,
@@ -7812,6 +9278,8 @@ export {
   SessionManager,
   SessionStore,
   SimpleModelRouter,
+  SkillRegistry,
+  SkillRuntime,
   StructuredLogger,
   SummaryService,
   ToolError,
@@ -7825,6 +9293,7 @@ export {
   classifyBashOutput,
   cleanupCommandResults,
   commandAuditSummary,
+  compareSkillPaths,
   createContextBudget,
   createDefaultLogSinks,
   createLogId,
@@ -7834,27 +9303,45 @@ export {
   describeModelError,
   detectShell,
   editFileTool,
+  escapeSkillXml,
+  estimateSkillTokens,
   executionFingerprint,
   extractFileDetails,
+  findSkillContent,
+  formatSkillCatalog,
   globTool,
   grepTool,
   identifyHistory,
   indexInteractions,
+  inspectSkillContent,
+  intersectSkillTools,
+  isSkillName,
   isTextBlock,
   isThinkingBlock,
   isToolResultBlock,
   isToolUseBlock,
+  isWithinSkillRoot,
+  listSkillResources,
   loadInstructions,
   normalizeHistory,
+  normalizeSkillTools,
+  parseSkillDocument,
   projectSafeFields,
+  readBoundedSkillText,
   readFileTool,
+  readSkillResource,
   recoverIncompleteAudit,
   renderFileDetails,
+  renderSkillReloads,
   requestFingerprint,
   resolveContextWindow,
   resolveSessionProject,
   sanitizeModelErrorMessage,
   sanitizeSessionTitle,
+  scanSkillRoot,
+  skillDigest,
+  skillFailure,
+  skillPathKey,
   stableJsonStringify,
   stableSerialize,
   supportsSessionState,