@kiturone/kapibala 0.0.4 → 0.0.6

package/dist/index.d.ts

@@ -1,3 +1,97 @@
+/** 技能知识来源；层级决定覆盖顺序，不授予文件或执行权限。 */
+type SkillScope = 'builtin' | 'global' | 'project';
+/** 结构化技能诊断；路径及文案需由宿主安全展示，不包含正文或凭据。 */
+interface SkillDiagnostic {
+    code: string;
+    level: 'warn' | 'error';
+    path: string;
+    message: string;
+    winnerPath?: string;
+    loserPath?: string;
+}
+/** 已校验的文件内容；available=false 的执行扩展仅供诊断，不得激活。 */
+interface SkillDocument {
+    name: string;
+    description: string;
+    body: string;
+    when?: string;
+    license?: string;
+    compatibility?: string;
+    argumentHint?: string;
+    metadata?: Readonly<Record<string, string>>;
+    frontmatter: Readonly<Record<string, unknown>>;
+    allowedTools?: readonly string[];
+    modelInvocable: boolean;
+    userInvocable: boolean;
+    available: boolean;
+    unavailableReason?: string;
+    diagnostics: readonly SkillDiagnostic[];
+}
+/** 宿主显式提供的扫描根；项目缺省不可信，boundary 必须是授权物理边界。 */
+interface SkillRoot {
+    path: string;
+    scope: SkillScope;
+    kind?: 'native' | 'agents';
+    trusted?: boolean;
+    boundary?: string;
+}
+/** 可查询元数据；文件指纹来自发现快照，加载前必须重新核验。 */
+interface SkillMetadata extends Omit<SkillDocument, 'body' | 'frontmatter' | 'diagnostics'> {
+    scope: SkillScope;
+    sourceRoot: string;
+    filePath: string;
+    baseDir: string;
+    contentDigest: string;
+    /** 原词法发现身份；加载重核根链接，不以旧物理文件继续授权。 */
+    discoveryRoot: string;
+    discoveryPath: string;
+    priority: number;
+    disabled: boolean;
+}
+/** 完整快照实体；正文仅在校验通过后按需进入模型历史。 */
+interface SkillDefinition extends SkillMetadata {
+    body: string;
+}
+/** 会话技能选项；无根即不扫描 home，disabled 名称不能由项目配置重新启用。 */
+interface SkillOptions {
+    roots: readonly SkillRoot[];
+    enabled?: boolean;
+    disabled?: readonly string[];
+}
+/** 技能正文持久来源；只追踪事实，历史来源不恢复授权。 */
+interface SkillContentSource {
+    version: 1;
+    name: string;
+    scope: SkillScope;
+    filePath: string;
+    baseDir: string;
+    contentDigest: string;
+    renderedDigest: string;
+    caller: 'user' | 'model';
+    runId: string;
+    invocationId: string;
+}
+/** 本轮活动记录；pending 只收紧，committed 后才可受控读取资源。 */
+interface SkillActivation {
+    definition: SkillDefinition;
+    source: SkillContentSource;
+    state: 'pending' | 'committed';
+    allowedTools?: ReadonlySet<string>;
+}
+/** 统一默认限额；宿主不得另算一套目录、文件或响应预算。 */
+declare const SKILL_LIMITS: Readonly<{
+    fileBytes: number;
+    frontmatterBytes: number;
+    depth: 6;
+    directories: 2000;
+    entries: 20000;
+    descriptionChars: 250;
+    catalogTokens: 2000;
+    queryTokens: 1000;
+    resourceBytes: number;
+    resourceFiles: 20;
+}>;
+
 /** 内置适配器的实际请求目标；用于拒绝模型、协议或端点错配的绑定。 */
 interface ModelProviderBinding {
     protocol: ModelProtocol;
@@ -137,10 +231,20 @@ declare class KapibalaError extends Error {
     readonly code: string;
     readonly retryPolicy: 'never' | 'immediate' | 'backoff' | 'after_user_action';
     readonly safeMessage: string;
+    readonly dispatchOutcome?: 'not_sent' | 'succeeded' | 'failed' | 'unknown';
     constructor(message: string, options?: {
         code?: string;
         retryPolicy?: 'never' | 'immediate' | 'backoff' | 'after_user_action';
         safeMessage?: string;
+        dispatchOutcome?: 'not_sent' | 'succeeded' | 'failed' | 'unknown';
+    });
+}
+/** 工具向外部发送前在微任务复核或状态检查中被撤销/拒绝；dispatchOutcome 固定 not_sent。 */
+declare class PreDispatchError extends KapibalaError {
+    constructor(message: string, options?: {
+        code?: string;
+        retryPolicy?: 'never' | 'after_user_action';
+        safeMessage?: string;
     });
 }
 /** 模型调用失败；message 已脱敏，对外诊断统一经 describeModelError 产出，retryPolicy 仅为处理建议。 */
@@ -242,9 +346,26 @@ interface ProviderStateBlock {
 }
 /** canonical 历史的内容块联合；provider_state 等私有块只在同 run、同模型与端点续答回传。 */
 type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock | ThinkingBlock | RedactedThinkingBlock | ProviderStateBlock;
+/**
+ * 宿主准备受控 Prompt 时的来源元数据（v1）。
+ * 用于追踪 Prompt 来源、版本与内容摘要；不保存认证值或重复保存原始参数，
+ * 不发送到 Provider wire，不从历史恢复授权。
+ */
+interface PromptContentSource {
+    version: 1;
+    server: string;
+    name: string;
+    scope?: string;
+    contentDigest?: string;
+    configIdentity?: string;
+}
 interface TextBlock {
     type: 'text';
     text: string;
+    /** 宿主注入技能的可选来源；只追踪正文，缺失或恢复不授予权限。 */
+    skillSource?: SkillContentSource;
+    /** 宿主注入受控 Prompt 的可选来源；只追踪正文与审计摘要，缺失或恢复不授予权限。 */
+    promptSource?: PromptContentSource;
     /** 源 wire Item 元数据；正文被改写后由调用方清除，不作为业务身份。 */
     protocolMeta?: ProtocolItemMetadata;
 }
@@ -260,8 +381,23 @@ interface ToolUseBlock {
     /** 源 wire Item 元数据；内容被改写后由调用方清除，不作为业务身份。 */
     protocolMeta?: ProtocolItemMetadata;
 }
+/**
+ * canonical 工具结果的可选 v1 执行事实元数据。
+ * 适配器按发送证据先记录 dispatchOutcome，执行器在发生本地钩子、校验、转换或审计失败时附加 hostError。
+ * 随 canonical 结果持久化；不直接上 Provider wire，不从历史中推断不存在的事实。
+ */
+interface ToolResultExecution {
+    version: 1;
+    dispatchOutcome: 'not_sent' | 'succeeded' | 'failed' | 'unknown';
+    hostError?: {
+        phase: 'validation' | 'projection' | 'hook' | 'audit';
+        code: string;
+    };
+}
 interface ToolResultBlock {
     type: 'tool_result';
+    /** 完整技能正文的宿主来源；不发送到Provider wire，不从历史恢复授权。 */
+    skillSource?: SkillContentSource;
     toolUseId: string;
     content: string;
     isError?: boolean;
@@ -271,6 +407,12 @@ interface ToolResultBlock {
     errorCode?: string;
     /** 不代表自动重试，只描述调用方应如何处理该错误。 */
     retryPolicy?: 'never' | 'immediate' | 'backoff' | 'after_user_action';
+    /**
+     * 可选 v1 执行事实元数据。
+     * 适配器按发送证据先记录 dispatchOutcome，执行器在发生本地钩子、校验、转换或审计失败时附加 hostError。
+     * 随 canonical 结果持久化；不直接上 Provider wire，不从历史中推断不存在的事实。
+     */
+    execution?: ToolResultExecution;
 }
 interface ThinkingBlock {
     type: 'thinking';
@@ -383,6 +525,11 @@ interface StepLogEntry {
  * 不应直接把本类型当作长期兼容的网络协议。
  */
 type SessionEvent = {
+    type: 'skill_loaded';
+    source: SkillContentSource;
+    messageId: string;
+    persistence: 'memory' | 'disk';
+} | {
     type: 'session_resumed';
     conversationId: string;
     runtimeSessionId: string;
@@ -484,6 +631,13 @@ type SessionEvent = {
     usage?: Usage;
     ttftMs?: number;
     durationMs?: number;
+} | {
+    type: 'mcp_prompt_loaded';
+    server: string;
+    name: string;
+    persistence: 'disk' | 'memory';
+    promptSource: PromptContentSource;
+    runId?: string;
 } | {
     type: 'turn_finish';
     turn: number;
@@ -1022,7 +1176,7 @@ declare class ContextManager {
     private publishSnapshot;
     /** 最终请求与只读估算共用来源和状态计数。 */
     private buildSnapshot;
-    /** 摘要以用户历史背景注入，不升级为系统指令或恢复旧授权。 */
+    /** 摘要与技能重载事实由已验证原历史生成，不升级为系统指令或恢复旧授权；旧检查点同样适用。 */
     private summaryMessage;
     /**
      * 旧轮次仅在工具事务闭合时可摘要；成功可由旧记录推断，失败或中断必须有运行终态来源。
@@ -1273,37 +1427,89 @@ interface InstructionLoadOptions {
  */
 declare function loadInstructions(options: InstructionLoadOptions): InstructionSnapshot;
 
-/** 受支持的解释器家族；wsl 是 Windows 上的 WSL bash launcher，路径与输出语义与 native bash 不同。 */
-type ShellKind = 'bash' | 'wsl' | 'pwsh' | 'powershell';
-/** auto / 具名解释器，或用户显式提供的解释器可执行文件全路径。 */
-type ShellPreference = 'auto' | ShellKind | (string & {});
-/** 探测成功后固定的解释器身份；executableDigest 参与命令审批指纹，解释器被替换即失配。 */
-interface ShellEnvironment {
-    kind: ShellKind;
-    executable: string;
-    executableDigest: string;
-    cwd: string;
+/** 安全名称语法；不接受厂商命名空间、路径或连续连字符。 */
+declare function isSkillName(value: string): boolean;
+/** 解析常用 Frontmatter 子集；格式错误抛出，未知执行扩展返回不可执行诊断，正文不截断。 */
+declare function parseSkillDocument(content: string, filePath: string): SkillDocument;
+
+/** 技能错误仅返回受控文案；retryPolicy 不触发工具内部重试。 */
+declare function skillFailure(code: string, message: string): KapibalaError;
+/** 以路径段判断物理边界，允许边界自身但不接受越界或其他盘符。 */
+declare function isWithinSkillRoot(root: string, target: string): boolean;
+/** Windows 物理身份忽略盘符/路径大小写，其他平台维持文件系统原义。 */
+declare function skillPathKey(value: string): string;
+/** 按 code point 排序，不使用受语言区域影响的比较器。 */
+declare function compareSkillPaths(left: string, right: string): number;
+/** 有界 UTF-8 读取；先检查文件类型/大小，增长中的文件也不能突破上限。 */
+declare function readBoundedSkillText(filePath: string, maximum: number, signal?: AbortSignal): Promise<string>;
+/** 原文件字节摘要；有效 UTF-8 的重新编码保留 BOM 与换行，不使用规范化正文替代。 */
+declare function skillDigest(content: string): string;
+/** 单根发现结果；诊断可包含无效候选，扫描结束后只保留元数据，不常驻正文。 */
+interface SkillScanResult {
+    skills: SkillMetadata[];
+    diagnostics: SkillDiagnostic[];
+}
+/** 扫描单根的技能边界；有界异步遍历，项目未声明信任时实体只供宿主诊断。 */
+declare function scanSkillRoot(root: SkillRoot, signal?: AbortSignal): Promise<SkillScanResult>;
+
+/** 使用现有 Unicode 估算器计完整文本，非 ASCII 不按四字符折算。 */
+declare function estimateSkillTokens(text: string): number;
+/** 技能元数据的 XML 转义；不把未转义的描述或路径当作目录结构。 */
+declare function escapeSkillXml(text: string): string;
+/** 完整目录投影及遗漏统计；text 为空表示最小目录也无法容纳。 */
+interface SkillCatalog {
+    text: string;
+    included: number;
+    omitted: number;
+    estimatedTokens: number;
+}
+/** 生成确定性 L2.5；预算含标题、XML、转义及遗漏提示，只删完整条目。 */
+declare function formatSkillCatalog(skills: readonly SkillMetadata[], contextWindow?: number, remainingTokens?: number): SkillCatalog;
+/** 模型目录分页输入；游标只定位快照，不提供信任或正文访问授权。 */
+interface SkillQuery {
+    query?: string;
+    cursor?: string;
+    limit?: number;
+}
+/** 有界模型元数据页；不包含正文，游标按实际返回条目推进。 */
+interface SkillQueryPage {
+    skills: {
+        name: string;
+        description: string;
+        scope: string;
+        argumentHint?: string;
+    }[];
+    total: number;
+    nextCursor?: string;
 }
-interface ShellDetectOptions {
-    /** 'auto'、具名解释器，或解释器可执行文件全路径；含路径分隔符或 .exe 后缀按显式路径处理。 */
-    preference?: ShellPreference;
-    /** 探测与后续执行的基准目录；探测前先取 realpath，符号链接会被展开。 */
-    cwd: string;
-    /** 以下两项供测试注入平台与 PATH；缺省取当前进程的值。 */
-    platform?: NodeJS.Platform;
-    pathEnv?: string;
+
+/** 确定性技能注册表；刷新原子替换快照，运行中加载必须与发现指纹一致。 */
+declare class SkillRegistry {
+    private readonly options;
+    private definitions;
+    private warnings;
+    private revisionValue;
+    /** 固定宿主配置副本，外部对象变更不能静默改变本轮发现或信任。 */
+    constructor(options: SkillOptions);
+    /** 获取独立诊断副本，调用方不能修改生效候选或权限。 */
+    get diagnostics(): SkillDiagnostic[];
+    /** 快照游标身份随正文、来源、可用性变化而失效。 */
+    get revision(): string;
+    /** 是否由宿主启用；关闭只影响本次能力，不删除历史或文件。 */
+    get enabled(): boolean;
+    /** 每轮开始重新发现；取消不发布半个快照，非法单文件只产生诊断。 */
+    refresh(signal?: AbortSignal): Promise<void>;
+    /** 按名称查询胜出元数据副本；未知名称返回 undefined，正文仅由 load 校验后懒读取。 */
+    get(name: string): SkillMetadata | undefined;
+    /** 宿主可检查不可用条目；模型/用户视图分别施加调用控制，均不读取正文。 */
+    list(caller?: 'host' | 'model' | 'user', query?: string): SkillMetadata[];
+    /** 按当前快照校验调用控制与物理身份，不接受模型提供的信任或 caller 升级。 */
+    load(name: string, caller: 'model' | 'user', signal?: AbortSignal): Promise<SkillDefinition>;
+    /** 查询可信模型集合；过期游标可修正，预算不足不返回不前进的分页。 */
+    queryModel(input?: SkillQuery, remainingTokens?: number): SkillQueryPage;
+    /** 复核配置根、词法发现路径和原文件字节，返回本次有界读取文本；漂移要求新运行，不能热替换。 */
+    verify(skill: SkillMetadata, signal?: AbortSignal): Promise<string>;
 }
-/**
- * 按 uname 输出分类 bash 家族：Git Bash/MSYS2/Cygwin 归 native bash，
- * Windows 上报告 Linux 的是 WSL launcher（独立 kind，路径语义不同）。
- */
-declare function classifyBashOutput(unameOutput: string, platform: NodeJS.Platform): ShellKind | undefined;
-/**
- * 发现并固定实际解释器：只用 PATH 与用户显式给出的路径，不写死任何安装目录。
- * auto 在 Windows 上按 native Bash → WSL → pwsh → powershell 依次兜底，
- * bash 家族用运行时 uname 探针区分 Git Bash 与 WSL launcher。
- */
-declare function detectShell(options: ShellDetectOptions): ShellEnvironment;
 
 /** 本次会话的自动执行边界；FullAccess 只能由宿主为本次会话显式选择。 */
 type SessionMode = 'Approval' | 'Plan' | 'Auto' | 'FullAccess';
@@ -1368,7 +1574,28 @@ declare class PermissionPolicy {
 declare function visibleTools(tools: readonly Tool[], mode: SessionMode, rules?: readonly PermissionRule[]): Tool[];
 
 /** 执行能力的最小分类；权限规则、模式裁决与工具元数据声明共用这一词汇表。 */
-type Capability = 'fs:read' | 'fs:write' | 'exec' | 'net:outbound' | 'env:read' | 'agent:spawn';
+type Capability = 'fs:read' | 'fs:write' | 'exec' | 'net:outbound' | 'env:read' | 'agent:spawn' | 'external:call';
+/**
+ * 外部调用的精确执行身份；供审批缓存、发送前复核与审计消费。
+ * 包含服务端物理身份、连接代次、目录 epoch 与定义摘要等不可伪造字段。
+ */
+interface ToolExecutionIdentity {
+    serverIdentity?: string;
+    connectionGeneration?: number;
+    catalogEpoch?: number;
+    toolDigest?: string;
+    [key: string]: unknown;
+}
+/**
+ * 显式 opt-in 规范化执行结果；普通对象返回值保持兼容不强制包装。
+ */
+interface ToolExecutionResult {
+    content: string;
+    isError?: boolean;
+    errorCode?: string;
+    retryPolicy?: 'never' | 'after_user_action';
+    execution?: ToolResultExecution;
+}
 interface ToolMetadata {
     /** 注册来源标记（如 'builtin'）；注册表据此执行冲突策略并支持按源注销。 */
     source?: string;
@@ -1378,6 +1605,8 @@ interface ToolMetadata {
     permissions?: Capability[];
     /** 工具自身等待进程资源回收，执行器不可再使用通用 Promise.race 超时。 */
     managesTimeout?: boolean;
+    /** 只读提示；工具声明自身无副作用，供 UI 展示与只读过滤参考。 */
+    readOnlyHint?: boolean;
 }
 /** 工具执行期由宿主注入的运行环境；信号取消后工具应尽快清理在途资源再返回。 */
 interface ToolContext {
@@ -1392,6 +1621,13 @@ interface ToolContext {
         outputBytes: number;
     }) => void;
 }
+/**
+ * 工具输入参数校验结果；valid 为 false 或抛出异常均阻止审批和发送。
+ */
+interface ToolInputValidation {
+    valid: boolean;
+    message?: string;
+}
 /** 工具契约；parameters 是 JSON Schema，模型只能看到经 toToolDefinition 投影后的三个字段。 */
 interface Tool<TInput = Record<string, unknown>, TOutput = unknown> {
     readonly name: string;
@@ -1400,6 +1636,12 @@ interface Tool<TInput = Record<string, unknown>, TOutput = unknown> {
     readonly metadata?: ToolMetadata;
     /** 声明本次输入的精确执行目标，供审批展示与执行前指纹复核；无固定执行目标的工具不实现。 */
     approvalScope?(input: TInput, rootDir: string): ShellScope;
+    /** 本次执行身份；审批缓存与执行前复核消费，缺省保持旧工具规则。 */
+    executionIdentity?(input: TInput, rootDir: string): ToolExecutionIdentity;
+    /** 无副作用地校验最终参数，不修改参数、不访问远端；异常与拒绝均阻止审批和发送。 */
+    validateInput?(input: TInput): ToolInputValidation | undefined;
+    /** 显式 opt-in 转换为标准执行结果；未提供时普通返回值继续作为常规输出。 */
+    toExecutionResult?(raw: TOutput): ToolExecutionResult;
     execute(input: TInput, ctx: ToolContext): Promise<TOutput>;
 }
 /** 恒等构造器：只为工具实现提供类型推断与统一书写形式，不产生任何运行时包装。 */
@@ -1407,75 +1649,32 @@ declare function defineTool<TInput = Record<string, unknown>, TOutput = unknown>
 /** 投影为模型可见的工具描述；刻意丢弃 metadata 与 approvalScope，执行侧信息不进入协议。 */
 declare function toToolDefinition(tool: Tool): ToolDefinition;
 
-/** run_command 的输入；cwd 相对工作区根解析，timeout_ms 合法区间 1..600000，越界在执行前失败。 */
-interface RunCommandInput {
-    [key: string]: unknown;
-    command: string;
-    cwd?: string;
-    timeout_ms?: number;
-}
-/** 命令执行结果；output 只是内联前缀，完整输出超过内联上限的部分落盘为受管结果文件。 */
-interface CommandResult {
-    /** 进程正常退出时的退出码；被信号终止时为 null。 */
-    exitCode: number | null;
-    /** stdout 与 stderr 交错合并的文本，最多前 64 KiB（按 UTF-8 字符边界截断）。 */
-    output: string;
-    /** output 并非全部输出的标志；超出内联上限的完整内容写入 outputFile。 */
-    outputTruncated: boolean;
-    /** 受管结果文件路径（工作区内 .kapibala/tool-results/），仅输出超过内联上限时存在。 */
-    outputFile?: string;
-    /** 结果文件触及 16 MiB 上限后被截断的标志。 */
-    outputFileTruncated: boolean;
-    /** 两个流产生的原始字节总数（不受截断影响），供进度与审计使用。 */
-    outputBytes: number;
-    shell: ShellEnvironment['kind'];
-}
-/** 仅清理受管 UUID 文件，避免删除用户在同目录保存的结果。 */
-declare function cleanupCommandResults(rootDir: string, now?: number): void;
-/** 使用固定解释器执行命令；超时和中止必须先处理进程树再返回。 */
-declare function createRunCommandTool(environment: ShellEnvironment): Tool<RunCommandInput, CommandResult>;
+/** 归一化技能白名单；参数模式/未知名称不得退化成宽泛命令授权。 */
+declare function normalizeSkillTools(skill: SkillDefinition, tools: readonly Tool[]): ReadonlySet<string> | undefined;
+/** 多活动技能白名单取交集；未声明不参与，空集合不等于无限制。 */
+declare function intersectSkillTools(activations: Iterable<Pick<SkillActivation, 'allowedTools'>>): ReadonlySet<string> | undefined;
 
-/** 路径沙箱配置；rootDir 是所有文件访问的词法与物理边界。 */
-interface SandboxConfig {
-    rootDir: string;
-    /**
-     * v0.0.1 恒为严格模式：任何解析后落在 rootDir 之外的物理路径一律拒绝，
-     * 不存在 fail-open 开关。该字段为 v0.0.2 权限引擎预留，当前不改变校验行为。
-     */
-    allowSymlinks?: boolean;
-}
-/**
- * 把文件访问限制在 rootDir 内：先做词法归一化检查，再展开符号链接做物理检查，两层都通过才放行。
- * 实例会缓存 rootDir 的物理路径，应按 rootDir 复用实例，而不是每次调用新建。
- */
-declare class PathSandbox {
-    readonly rootDir: string;
-    readonly allowSymlinks: boolean;
-    private cachedRealRootDir?;
-    constructor(config: SandboxConfig);
-    /**
-     * rootDir 的物理路径。rootDir 自身可能是一个符号链接(如 macOS 的 /var → /private/var)，
-     * 必须先归一化，否则物理路径与 rootDir 比较时会产生误判。
-     */
-    private get realRootDir();
-    /**
-     * 检查并解析安全路径
-     * 1. 解析相对路径为相对于 rootDir 的绝对路径
-     * 2. 词法检查：`..` 归一化后必须仍在 rootDir 内
-     * 3. 物理检查：解析符号链接后的真实路径必须仍在 rootDir 内
-     */
-    resolveSafePath(targetPath: string): string;
-    /**
-     * 把词法路径映射为物理路径。
-     *
-     * 关键点在于**向上回溯到最近一个真实存在的祖先**再取 realpath，然后把尚未存在的尾段拼回去：
-     * - 目标已存在 → 直接 realpath，符号链接立刻被展开；
-     * - 目标不存在(典型场景：write_file 新建文件) → 若只看目标本身，所有校验都会被跳过，
-     *   于是 `write_file('linkDir/new.txt')` 可以借道指向外部的 linkDir 越界写入。
-     *   回溯到 linkDir 取 realpath 即可识破这种穿透。
-     */
-    private toPhysicalPath;
+/** 受控文本范围；offset 用于 UTF-8 大行续读，不能与行范围混用。 */
+interface SkillResourceInput {
+    name: string;
+    path: string;
+    startLine?: number;
+    endLine?: number;
+    offset?: number;
 }
+/** 只读资源页；nextOffset 是完整 UTF-8 字符边界，不代表文件执行授权。 */
+interface SkillResourcePage {
+    text: string;
+    truncated: boolean;
+    nextOffset?: number;
+}
+/** 读取技能根内文本；复核物理边界，有界返回并关闭文件，不扩大普通文件沙箱。 */
+declare function readSkillResource(skill: SkillDefinition, input: SkillResourceInput, signal?: AbortSignal): Promise<SkillResourcePage>;
+/** 限量列出包内资源名而不读取正文；外部链接、默认忽略目录及深层资源不展开。 */
+declare function listSkillResources(skill: SkillDefinition, signal?: AbortSignal): Promise<{
+    files: string[];
+    truncated: boolean;
+}>;
 
 /**
  * 人工审批的五选一结果。allow_once / deny_once 只作用于本次执行；
@@ -1490,6 +1689,10 @@ interface ApprovalRequest {
     input: Record<string, unknown>;
     rootDir: string;
     shell?: ShellScope;
+    /**
+     * 本次调用的外部执行身份；深度哈希纳入审批缓存键，断连重连或目录变更后旧会话批准自动失效。
+     */
+    executionIdentity?: ToolExecutionIdentity;
     /** 宿主是否允许本次请求写入会话级允许缓存；deny_session 的缓存不受此限制。 */
     sessionAllowed: boolean;
 }
@@ -1509,71 +1712,70 @@ declare class SessionApprovalCache {
 
 /** 同名工具冲突策略：error 直接抛错；prefer-builtin 保留既有内置注册；prefer-last 后到者覆盖。 */
 type ConflictPolicy = 'error' | 'prefer-builtin' | 'prefer-last';
+/**
+ * 不可变工具注册表快照；捕获特定时刻的工具定义、执行引用与版本。
+ * 外部注册表后续的增删改绝不改写已有快照视图。
+ */
+interface ToolRegistrySnapshot {
+    readonly version: number;
+    get(name: string): Tool | undefined;
+    has(name: string): boolean;
+    resolve(name: string): Tool;
+    list(): Tool[];
+    definitions(): ToolDefinition[];
+    sourceOf(name: string): string | undefined;
+}
 /**
  * 按名称索引的工具注册表。冲突按构造时给定的策略处理，胜出条目的来源标签保持不变；
- * 来源标签支持按源批量注册与注销，注销只移除以该标签注册的工具，不回收冲突中保留的内置实现。
+ * 支持原子来源替换（replaceSource）、不可变运行快照（snapshot）与来源注销。
  */
 declare class ToolRegistry {
     private readonly tools;
     private readonly toolSources;
     private readonly conflictPolicy;
+    private version;
     constructor(options?: {
         conflictPolicy?: ConflictPolicy;
     });
+    /** 获取当前注册表版本号；每次有效变更（注册、替换、注销）单调自增。 */
+    get currentVersion(): number;
     register(tool: Tool, opts?: {
         source?: string;
     }): void;
+    /**
+     * 原子替换指定来源的全部工具：
+     * 1. 预检候选批内自身重名：若候选批次内包含同名工具，整批拒绝；
+     * 2. 预检跨来源冲突：若候选工具被其它来源占用且策略不允许覆盖，整批拒绝；
+     * 3. 同步原子提交：预检全部通过后一次性清理该来源旧工具并写入新工具；失败时完全保持旧状态不变。
+     */
+    replaceSource(source: string, tools: Tool[]): void;
+    /**
+     * 注册指定来源的工具集。
+     *
+     * 语义与约束：
+     * 1. 委托给 `replaceSource` 实现整源原子替换（新集合未包含的该来源旧工具将被注销移除，非增量累加）；
+     * 2. 默认禁止跨来源名称冲突（抛出 KapibalaError TOOL_CONFLICT）；若 options 配置了 conflictPolicy: 'prefer-last' 则允许覆盖旧来源同名工具；
+     * 3. 预检阶段发现批内同名重复时整批拒绝，绝不破坏注册表原子状态。
+     */
     registerSource(source: string, tools: Tool[]): void;
     unregisterSource(source: string): void;
     get(name: string): Tool | undefined;
+    has(name: string): boolean;
+    /** 获取工具对应的来源标记。 */
+    sourceOf(name: string): string | undefined;
+    /** 注销指定名称及来源记录；调用方须核对实例身份，不能移除同名替代工具。 */
+    unregister(name: string): void;
     /** 未命中时抛 ToolNotFound，并携带当前全部可用名称辅助模型自纠。 */
     resolve(name: string): Tool;
     list(): Tool[];
     definitions(): ToolDefinition[];
+    /**
+     * 捕获当前注册表的不可变只读快照。
+     * 注册表后续的增删改绝不改变该快照的定义列表、工具执行实例与来源版本。
+     */
+    snapshot(): ToolRegistrySnapshot;
 }
 
-declare const readFileTool: Tool<{
-    path: string;
-    startLine?: number;
-    endLine?: number;
-}, string>;
-declare const writeFileTool: Tool<{
-    path: string;
-    content: string;
-}, string>;
-declare const editFileTool: Tool<{
-    path: string;
-    targetContent: string;
-    replacementContent: string;
-}, string>;
-declare const globTool: Tool<{
-    pattern: string;
-    subDirectory?: string;
-}, string>;
-declare const grepTool: Tool<{
-    pattern: string;
-    path?: string;
-}, string>;
-/** 五个内置文件工具的聚合；全部经 PathSandbox 校验，路径越界或符号链接穿透一律拒绝。 */
-declare const builtinTools: (Tool<{
-    path: string;
-    startLine?: number;
-    endLine?: number;
-}, string> | Tool<{
-    path: string;
-    content: string;
-}, string> | Tool<{
-    path: string;
-    targetContent: string;
-    replacementContent: string;
-}, string> | Tool<{
-    pattern: string;
-    subDirectory?: string;
-}, string> | Tool<{
-    pattern: string;
-    path?: string;
-}, string>)[];
-
 /**
  * 运行时钩子契约：宿主与插件在固定切点观察或调整流程。
  * 通知型切点由 HookRegistry.emit 串行触发；需要返回值的 model:before / tool:before
@@ -1639,26 +1841,20 @@ declare class HookRegistry {
     emit<K extends 'session:start' | 'session:end' | 'model:after' | 'tool:after' | 'error'>(point: K, ctx: HookContext, ...args: any[]): Promise<void>;
 }
 
-/** setup 收到的能力入口；tools / hooks 是会话共享的注册表，注册的条目影响后续所有执行。 */
-interface PluginContext {
-    readonly tools: ToolRegistry;
-    readonly hooks: HookRegistry;
-    /** 本次会话的绝对工具根目录；工具的路径解析与审批都以此为基准。 */
-    readonly rootDir: string;
-    readonly logger?: (msg: string) => void;
-}
-/** 插件生命周期：setup 在会话空闲时挂载执行一次，teardown 在会话销毁时逐个调用以回收资源。 */
-interface AgentPlugin {
-    /** 用于挂载失败与 teardown 的诊断信息。 */
-    readonly name: string;
-    readonly version?: string;
-    setup(ctx: PluginContext): void | Promise<void>;
-    teardown?(): void | Promise<void>;
-}
-
 /** ToolExecutor 的构造项；审计写入需要 eventLogger 与 sessionId 同时提供，否则不产生审计。 */
+/** 宿主运行级硬限制；优先于模式、审批及缓存，文案和字段不得携带凭据。 */
+interface ToolHardDenial {
+    code: string;
+    message: string;
+    retryPolicy: ToolResultBlock['retryPolicy'];
+    fields?: Record<string, unknown>;
+}
 interface ExecutorOptions {
-    tools: ToolRegistry;
+    /** 在最终参数上补充硬拒绝，不能把拒绝转为授权。 */
+    hardDenial?: (tool: Tool, input: Record<string, unknown>) => ToolHardDenial | undefined;
+    /** 结果钩子和执行审计完成后调用；用于在同批次下一调用前安装宿主收紧状态。 */
+    onToolResult?: (tool: Tool, input: Record<string, unknown>, result: ToolResultBlock) => void | Promise<void>;
+    tools: ToolRegistry | ToolRegistrySnapshot;
     hooks: HookRegistry;
     /** 工具执行的绝对根目录；路径解析与审批均以此为基准。 */
     rootDir: string;
@@ -1684,6 +1880,8 @@ interface ExecutorOptions {
  * 同一 run 内参数完全相同的 never 失败会被拒绝重复执行。
  */
 declare class ToolExecutor {
+    private readonly hardDenial?;
+    private readonly onToolResult?;
     private readonly tools;
     private readonly hooks;
     private readonly rootDir;
@@ -1703,13 +1901,16 @@ declare class ToolExecutor {
     constructor(options: ExecutorOptions);
     /** 中止本轮正在等待或执行的工具；调用方仍须等待 runAll 完成资源回收及结果审计。 */
     cancel(): void;
-    /** 串行执行全部调用并返回与入参顺序一致的结果；某个结果要求用户介入后，其余调用直接拒绝。 */
+    /**
+     * 串行执行全部调用并返回与入参顺序一致的结果；某个结果要求用户介入后，其余调用直接拒绝。
+     * onResult 在每个最终结果（含拒绝/失败）产生后提供独立快照，供在途预算估算，不代表历史已提交；回调不得抛错。
+     */
     runAll(calls: ToolUseBlock[], onProgress?: (event: {
         id: string;
         name: string;
         elapsedMs: number;
         outputBytes: number;
-    }) => void): Promise<ToolResultBlock[]>;
+    }) => void, onResult?: (result: ToolResultBlock) => void): Promise<ToolResultBlock[]>;
     /**
      * 在最终参数上裁决并审计一次调用，所有拒绝和异常均闭合为工具结果。
      * 为调用记录本次绝对工具根目录，供跨目录恢复后的文件事实解析；不使用历史目录授权。
@@ -1731,6 +1932,280 @@ declare class ToolExecutor {
     private withTimeout;
 }
 
+/** 加载预检结果；只有最终成功工具结果或真实用户消息提交后才形成活动资格。 */
+interface PreparedSkill {
+    /** 本轮完整正文仍可见时只引用，引用结果不附完整正文来源。 */
+    alreadyPresent?: boolean;
+    definition: SkillDefinition;
+    source: SkillContentSource;
+    text: string;
+    allowedTools?: ReadonlySet<string>;
+}
+/** 会话内技能运行状态；控制工具按实例身份识别，pending 只收紧而不授予资源。 */
+declare class SkillRuntime {
+    readonly registry: SkillRegistry;
+    private readonly tools;
+    private readonly onResourceRead?;
+    readonly loaderTool: Tool;
+    readonly queryTool: Tool;
+    readonly resourceTool: Tool;
+    private readonly controls;
+    private readonly prepared;
+    private readonly active;
+    private runId;
+    private history;
+    private projection;
+    private reservedTokens;
+    private remaining;
+    /** 注册表和工具集合属于一个Session；不跨会话共享授权或隐式目录。 */
+    constructor(registry: SkillRegistry, tools: ToolRegistry, onResourceRead?: ((source: SkillContentSource, input: SkillResourceInput, page: SkillResourcePage) => Promise<void>) | undefined);
+    /**
+     * 开始新运行；历史正文只作事实，必须由本轮加载重新激活。
+     * remaining 必须扣除在途 assistant 和普通工具结果；尚未提交的成功技能正文由本类独立预留，不重复扣除。
+     */
+    begin(runId: string, history: () => readonly CanonicalMessage[], remaining: () => number, projection?: () => readonly CanonicalMessage[]): void;
+    /** 按实际集合安装实例工具；同名插件不覆盖为受信任工具，也不能制造目录引导。 */
+    syncTools(): void;
+    /** 清空本轮状态；调用方必须先等待工具和历史事务清理，不能提前释放会话锁。 */
+    clear(): void;
+    /** 查询本轮活动状态副本，避免宿主修改限制。 */
+    get activations(): SkillActivation[];
+    /** 预检正文、限制和输入空间；调用方由宿主固定，不读取模型伪造caller。 */
+    prepare(name: string, caller: 'model' | 'user', signal?: AbortSignal): Promise<PreparedSkill>;
+    /** 真实用户入口安装pending；正文需进入用户消息，提交前不提供资源。 */
+    acceptUser(prepared: PreparedSkill): void;
+    /** 最终工具结果通过执行器钩子/审计后安装收紧；同名或仿造结果不激活。 */
+    acceptResult(tool: Tool, result: ToolResultBlock): void;
+    /** 业务调用的动态硬拒绝；控制工具仅按实例豁免，仍须宿主权限裁决。 */
+    denial(tool: Tool): ToolHardDenial | undefined;
+    /** 完整消息提交后记录审计再发布事件；失败不回滚历史，但不提交资源资格。 */
+    commit(audit: (source: SkillContentSource, messageId: string) => Promise<void>, persistence: 'memory' | 'disk'): Promise<SessionEvent[]>;
+    /** 检查最终模型投影的完整活动指导；钩子或压缩不能移走后继续执行。 */
+    assertProjection(messages: readonly CanonicalMessage[]): void;
+    /** 只读本轮已提交技能资源；文件/来源漂移要求重新开始，不重放脚本。 */
+    readResource(input: SkillResourceInput, signal?: AbortSignal): Promise<SkillResourcePage>;
+}
+
+/** 技能正文在实际投影中的状态；来源只关联事实，present 不代表当前运行获得授权。 */
+interface SkillContextState {
+    source: SkillContentSource;
+    messageId: string;
+    state: 'present' | 'requires_reload';
+}
+/** 查找真实投影中的完整正文来源；字段缺失、未知版本或文本摘要不匹配不用于去重。 */
+declare function findSkillContent(history: readonly CanonicalMessage[], source: SkillContentSource): {
+    messageId: string;
+    source: SkillContentSource;
+} | undefined;
+/** 比较原始来源与真实投影，以最后一次相同文件/版本正文为准；不恢复旧授权或执行动作。 */
+declare function inspectSkillContent(raw: readonly CanonicalMessage[], projected: readonly CanonicalMessage[]): SkillContextState[];
+/** 将离开投影的旧正文表示为有界重载事实；最多50条，遗漏数明确，不把历史包装成当前指令。 */
+declare function renderSkillReloads(covered: readonly CanonicalMessage[]): string;
+
+/** 受支持的解释器家族；wsl 是 Windows 上的 WSL bash launcher，路径与输出语义与 native bash 不同。 */
+type ShellKind = 'bash' | 'wsl' | 'pwsh' | 'powershell';
+/** auto / 具名解释器，或用户显式提供的解释器可执行文件全路径。 */
+type ShellPreference = 'auto' | ShellKind | (string & {});
+/** 探测成功后固定的解释器身份；executableDigest 参与命令审批指纹，解释器被替换即失配。 */
+interface ShellEnvironment {
+    kind: ShellKind;
+    executable: string;
+    executableDigest: string;
+    cwd: string;
+}
+interface ShellDetectOptions {
+    /** 'auto'、具名解释器，或解释器可执行文件全路径；含路径分隔符或 .exe 后缀按显式路径处理。 */
+    preference?: ShellPreference;
+    /** 探测与后续执行的基准目录；探测前先取 realpath，符号链接会被展开。 */
+    cwd: string;
+    /** 以下两项供测试注入平台与 PATH；缺省取当前进程的值。 */
+    platform?: NodeJS.Platform;
+    pathEnv?: string;
+}
+/**
+ * 按 uname 输出分类 bash 家族：Git Bash/MSYS2/Cygwin 归 native bash，
+ * Windows 上报告 Linux 的是 WSL launcher（独立 kind，路径语义不同）。
+ */
+declare function classifyBashOutput(unameOutput: string, platform: NodeJS.Platform): ShellKind | undefined;
+/**
+ * 发现并固定实际解释器：只用 PATH 与用户显式给出的路径，不写死任何安装目录。
+ * auto 在 Windows 上按 native Bash → WSL → pwsh → powershell 依次兜底，
+ * bash 家族用运行时 uname 探针区分 Git Bash 与 WSL launcher。
+ */
+declare function detectShell(options: ShellDetectOptions): ShellEnvironment;
+
+/** run_command 的输入；cwd 相对工作区根解析，timeout_ms 合法区间 1..600000，越界在执行前失败。 */
+interface RunCommandInput {
+    [key: string]: unknown;
+    command: string;
+    cwd?: string;
+    timeout_ms?: number;
+}
+/** 命令执行结果；output 只是内联前缀，完整输出超过内联上限的部分落盘为受管结果文件。 */
+interface CommandResult {
+    /** 进程正常退出时的退出码；被信号终止时为 null。 */
+    exitCode: number | null;
+    /** stdout 与 stderr 交错合并的文本，最多前 64 KiB（按 UTF-8 字符边界截断）。 */
+    output: string;
+    /** output 并非全部输出的标志；超出内联上限的完整内容写入 outputFile。 */
+    outputTruncated: boolean;
+    /** 受管结果文件路径（工作区内 .kapibala/tool-results/），仅输出超过内联上限时存在。 */
+    outputFile?: string;
+    /** 结果文件触及 16 MiB 上限后被截断的标志。 */
+    outputFileTruncated: boolean;
+    /** 两个流产生的原始字节总数（不受截断影响），供进度与审计使用。 */
+    outputBytes: number;
+    shell: ShellEnvironment['kind'];
+}
+/** 仅清理受管 UUID 文件，避免删除用户在同目录保存的结果。 */
+declare function cleanupCommandResults(rootDir: string, now?: number): void;
+/** 使用固定解释器执行命令；超时和中止必须先处理进程树再返回。 */
+declare function createRunCommandTool(environment: ShellEnvironment): Tool<RunCommandInput, CommandResult>;
+
+/** 路径沙箱配置；rootDir 是所有文件访问的词法与物理边界。 */
+interface SandboxConfig {
+    rootDir: string;
+    /**
+     * v0.0.1 恒为严格模式：任何解析后落在 rootDir 之外的物理路径一律拒绝，
+     * 不存在 fail-open 开关。该字段为 v0.0.2 权限引擎预留，当前不改变校验行为。
+     */
+    allowSymlinks?: boolean;
+}
+/**
+ * 把文件访问限制在 rootDir 内：先做词法归一化检查，再展开符号链接做物理检查，两层都通过才放行。
+ * 实例会缓存 rootDir 的物理路径，应按 rootDir 复用实例，而不是每次调用新建。
+ */
+declare class PathSandbox {
+    readonly rootDir: string;
+    readonly allowSymlinks: boolean;
+    private cachedRealRootDir?;
+    constructor(config: SandboxConfig);
+    /**
+     * rootDir 的物理路径。rootDir 自身可能是一个符号链接(如 macOS 的 /var → /private/var)，
+     * 必须先归一化，否则物理路径与 rootDir 比较时会产生误判。
+     */
+    private get realRootDir();
+    /**
+     * 检查并解析安全路径
+     * 1. 解析相对路径为相对于 rootDir 的绝对路径
+     * 2. 词法检查：`..` 归一化后必须仍在 rootDir 内
+     * 3. 物理检查：解析符号链接后的真实路径必须仍在 rootDir 内
+     */
+    resolveSafePath(targetPath: string): string;
+    /**
+     * 把词法路径映射为物理路径。
+     *
+     * 关键点在于**向上回溯到最近一个真实存在的祖先**再取 realpath，然后把尚未存在的尾段拼回去：
+     * - 目标已存在 → 直接 realpath，符号链接立刻被展开；
+     * - 目标不存在(典型场景：write_file 新建文件) → 若只看目标本身，所有校验都会被跳过，
+     *   于是 `write_file('linkDir/new.txt')` 可以借道指向外部的 linkDir 越界写入。
+     *   回溯到 linkDir 取 realpath 即可识破这种穿透。
+     */
+    private toPhysicalPath;
+}
+
+declare const readFileTool: Tool<{
+    path: string;
+    startLine?: number;
+    endLine?: number;
+}, string>;
+declare const writeFileTool: Tool<{
+    path: string;
+    content: string;
+}, string>;
+declare const editFileTool: Tool<{
+    path: string;
+    targetContent: string;
+    replacementContent: string;
+}, string>;
+declare const globTool: Tool<{
+    pattern: string;
+    subDirectory?: string;
+}, string>;
+declare const grepTool: Tool<{
+    pattern: string;
+    path?: string;
+}, string>;
+/** 五个内置文件工具的聚合；全部经 PathSandbox 校验，路径越界或符号链接穿透一律拒绝。 */
+declare const builtinTools: (Tool<{
+    path: string;
+    startLine?: number;
+    endLine?: number;
+}, string> | Tool<{
+    path: string;
+    content: string;
+}, string> | Tool<{
+    path: string;
+    targetContent: string;
+    replacementContent: string;
+}, string> | Tool<{
+    pattern: string;
+    subDirectory?: string;
+}, string> | Tool<{
+    pattern: string;
+    path?: string;
+}, string>)[];
+
+/** setup 收到的能力入口；tools / hooks 是会话共享的注册表，注册的条目影响后续所有执行。 */
+interface PluginContext {
+    readonly tools: ToolRegistry;
+    readonly hooks: HookRegistry;
+    /** 本次会话的绝对工具根目录；工具的路径解析与审批都以此为基准。 */
+    readonly rootDir: string;
+    readonly logger?: (msg: string) => void;
+}
+/**
+ * 插件声明的命令贡献描述元数据。
+ *
+ * 约束、边界与为什么：
+ * 1. 纯元数据定义：只包含名称、描述、用法与变更标记，禁止引入 ANSI 渲染、Readline 或 TTY 依赖，坚守 Core Headless 铁律；
+ * 2. 供宿主（CLI/TUI/Web）按需消费并装配到人机交互界面；非交互或 Headless 宿主可安全忽略本字段；
+ * 3. 别名与主名均遵循全小写规范，防止跨平台输入歧义。
+ */
+interface PluginCommandContribution {
+    /** 命令主名称（不含前导斜杠，如 'mcp' 或 'prompts'）。 */
+    readonly name: string;
+    /** 命令用途说明，供帮助菜单展示。 */
+    readonly description: string;
+    /** 格式化调用用法（如 '/mcp [tools <server>]'）。 */
+    readonly usage?: string;
+    /** 可选别名列表（如 ['plugin']）。 */
+    readonly aliases?: readonly string[];
+    /** 命令是否产生状态变更；true 表示写操作（受忙碌状态门拦截），false 表示纯只读诊断。 */
+    readonly mutates?: boolean;
+}
+/**
+ * 插件声明的扩展贡献元数据聚合容器。
+ *
+ * 约束与边界：
+ * 1. 声明式规范：允许外部扩展包一次性声明技能根目录、交互命令与扩展元数据；
+ * 2. 宿主（CLI）在会话挂载插件时自动读取并完成装配，无需在宿主层硬编码插件内部命令。
+ */
+interface PluginContribution {
+    /** 插件显式携带或依赖的技能根目录集合（绝对物理路径）。 */
+    readonly skillsRoots?: readonly string[];
+    /** 插件贡献给宿主交互终端的斜杠命令列表。 */
+    readonly commands?: readonly PluginCommandContribution[];
+}
+/**
+ * 插件生命周期契约：setup 在会话空闲时挂载执行一次，teardown 在会话销毁时逐个调用以回收资源。
+ * 遵循「一 Session 一插件实例」约束，实现外部生态向 Agent Harness 的受控单向注入。
+ */
+interface AgentPlugin {
+    /** 插件唯一识别名称，用于诊断输出与依赖追踪。 */
+    readonly name: string;
+    /** 插件语义版本号，默认遵循包版本。 */
+    readonly version?: string;
+    /** 插件用途与功能描述。 */
+    readonly description?: string;
+    /** 插件声明的扩展贡献元数据（命令清单、技能目录等）。 */
+    readonly contributes?: PluginContribution;
+    /** 挂载执行入口；仅在空闲状态调用，可向 tools / hooks 注册能力。 */
+    setup(ctx: PluginContext): void | Promise<void>;
+    /** 销毁回收入口；必须幂等执行，彻底清理进程、网络连接或定时器。 */
+    teardown?(): void | Promise<void>;
+}
+
 /** Chat 端点配置；能力覆盖只改变请求字段和完成边界，不改变协议身份。 */
 interface OpenAIProviderOptions {
     baseURL: string;
@@ -1866,9 +2341,15 @@ declare class OpenAIResponsesProvider implements ModelProvider {
     private toUsage;
 }
 
+/** 分层提示选项；目录受实际工具定义和请求剩余空间约束，不能用同名工具冒充加载能力。 */
 interface PromptAssemblerOptions {
+    /** 可信技能快照；仅匹配加载工具实例实际可见时注入L2.5。 */
+    skills?: SkillRegistry;
+    skillLoader?: Tool;
+    contextWindow?: number;
+    skillBudgetTokens?: number;
     /** 提供时才生成 L2 工具清单段；缺省表示本次运行不向模型展示任何工具。 */
-    tools?: ToolRegistry;
+    tools?: ToolRegistry | ToolRegistrySnapshot;
     /** L3 环境段展示的工作区根目录；文件工具的沙箱边界与其保持一致。 */
     rootDir: string;
     agentName?: string;
@@ -1884,6 +2365,7 @@ interface PromptAssemblerOptions {
  * 各段之间以 `\n\n---\n\n` 分隔；不提供的内容整段跳过，不做占位填充。
  */
 declare class PromptAssembler {
+    private readonly options;
     private readonly tools?;
     private readonly rootDir;
     private readonly agentName;
@@ -1893,11 +2375,14 @@ declare class PromptAssembler {
     constructor(options: PromptAssemblerOptions);
     /** 按固定层级拼装系统提示词；同一选项集总是产出相同文本，便于审计与缓存。 */
     assemble(): string;
+    /** 返回与 assemble 相同的目录统计；加载器被隐藏、替换或禁用时省略执行目录。 */
+    getSkillCatalog(): SkillCatalog;
     private getL1Behavior;
     private getL2Tools;
     private getL3Environment;
 }
 
+/** 循环宿主配置；请求投影与在途预算只操作临时视图，历史仍按完整工具事务追加。 */
 interface AgentLoopOptions {
     /** 本次交互身份，内部步骤仍独立编号。 */
     interactionId?: string;
@@ -1910,9 +2395,11 @@ interface AgentLoopOptions {
     prepareRequest?: RequestPreparation;
     /** 每次收到 usage 后回调；attemptId 标识 run:step:attempt，便于按尝试归因。 */
     onUsage?: (request: ModelRequest, usage: Usage, attemptId: string) => Promise<void>;
+    /** 在途批次预算视图；含当前 assistant 和已完成结果，不能作为落盘或授权依据，闭合后清空；回调不得抛错。 */
+    onToolBatchUpdate?: (messages: readonly CanonicalMessage[]) => void;
     provider: ModelProvider;
     executor: ToolExecutor;
-    tools: ToolRegistry;
+    tools: ToolRegistry | ToolRegistrySnapshot;
     hooks: HookRegistry;
     systemPrompt?: string;
     /** 单次 run 的最大 turn 数，耗尽时以 error 事件收尾；缺省 20。 */
@@ -1939,6 +2426,7 @@ declare class AgentLoop {
     private readonly projectHistory?;
     private readonly prepareRequest?;
     private readonly onUsage?;
+    private readonly onToolBatchUpdate?;
     private readonly provider;
     private readonly executor;
     private readonly tools;
@@ -1964,8 +2452,32 @@ declare class AgentLoop {
     run(history: CanonicalMessage[]): AsyncIterable<SessionEvent>;
 }
 
+/**
+ * 任务准备上下文；提供当前会话取消信号、runId 与不可变工具快照。
+ */
+interface PreparedTaskContext {
+    signal?: AbortSignal;
+    runId: string;
+    tools: ToolRegistrySnapshot;
+}
+/**
+ * 任务准备产物；包含要附加到 User 消息的内容块，以及提交前的身份复核回调。
+ */
+interface PreparedTaskResult {
+    /** 任务附加内容块或纯文本（如 Prompt 内容或技能正文）。 */
+    content: ContentBlock[] | string;
+    /** 可选来源元数据；仅在 content 为 string 时由宿主自动包装为带来源的 TextBlock。 */
+    promptSource?: PromptContentSource;
+    /** 最终提交前核对准备身份；若在此期间目录变化或连接重置，返回 false 拒绝提交并零发送闭合。 */
+    verifyIdentity?: () => boolean | Promise<boolean>;
+    /** 可选技能名称；存在时按显式技能流程处理。 */
+    skillName?: string;
+}
+
 /** AgentSession 的构造配置；除主任务绑定外均可缺省，缺省行为见各字段。 */
 interface SessionConfig {
+    /** 宿主显式技能配置；缺省不扫描home，项目根需独立信任。 */
+    skills?: SkillOptions;
     /** 持久会话身份；有版本化 Store 时须与头部一致，日志实例身份保持独立。 */
     conversationId?: string;
     tokenEstimator?: TokenEstimator;
@@ -2022,6 +2534,8 @@ interface SessionStats {
  * 运行或清理进行中，改变状态的公开方法一律被拒绝；Core 不承担任何界面职责。
  */
 declare class AgentSession {
+    private readonly skillRegistry?;
+    private readonly skillRuntime?;
     private persistentId;
     private readonly configuredConversationId?;
     private readonly estimator?;
@@ -2073,6 +2587,12 @@ declare class AgentSession {
     init(): Promise<void>;
     /** 挂载插件并执行 setup；销毁后或运行中拒绝，setup 失败的插件不进入已装列表。 */
     use(plugin: AgentPlugin): Promise<void>;
+    /**
+     * 获取当前会话已成功挂载的扩展插件只读列表。
+     *
+     * 保证返回当前状态的独立切片，外部修改不污染内部挂载表。
+     */
+    getPlugins(): readonly AgentPlugin[];
     /**
      * 空闲时原子替换角色的模型绑定；本方法不改变当前角色或工具权限。
      * @param profile 模型协议、请求目标和输出预算。
@@ -2093,6 +2613,8 @@ declare class AgentSession {
     /** 只在空闲时切换本次会话模式；宿主负责 FullAccess 的显式选择交互。 */
     switchMode(mode: SessionMode): void;
     getMode(): SessionMode;
+    /** 获取当前会话生效的权限规则列表。 */
+    getPermissionRules(): readonly PermissionRule[];
     /** 返回最近一次成功装载的来源路径，不暴露指令正文。 */
     getInstructionSources(): string[];
     /** 稳定会话身份，独立于当前进程日志实例和每次用户交互。 */
@@ -2101,6 +2623,17 @@ declare class AgentSession {
     getHistory(): CanonicalMessage[];
     /** 返回当前投影视图，区别于原始历史；不执行模型或 Hook。 */
     getContextHistory(): CanonicalMessage[];
+    /** 查询技能元数据、诊断与本轮活动状态；只读，不加载正文或改变权限。 */
+    getSkills(query?: string): {
+        skills: SkillMetadata[];
+        diagnostics: SkillDiagnostic[];
+        activations: SkillActivation[];
+        content: SkillContextState[];
+        catalog: {
+            included: number;
+            omitted: number;
+        };
+    };
     /** 查询最近最终请求的预算快照，尚未准备请求时返回 undefined。 */
     getContextSnapshot(): ContextSnapshot | undefined;
     /** 执行中止后的工具/摘要与存储收口期间仍返回 true。 */
@@ -2129,11 +2662,35 @@ declare class AgentSession {
         signal?: AbortSignal;
         role?: PrimaryModelRole;
     }): AsyncIterable<SessionEvent>;
+    /** 显式用户技能入口；任务原文单条提交，与普通run共享互斥、取消及清理，不恢复历史授权。 */
+    runSkill(name: string, task: string, options?: {
+        signal?: AbortSignal;
+        role?: PrimaryModelRole;
+    }): AsyncIterable<SessionEvent>;
+    /**
+     * 受控任务准备入口：在同一运行锁内异步准备文本块/来源，预算和存储成功后才进入模型。
+     *
+     * @param task 用户显式任务正文（或命令描述）。
+     * @param prepare 异步任务准备函数；在锁内执行，若准备失败或取消则释放锁且零 append。
+     * @param options 可选中止信号与显式主任务角色。
+     * @returns 结构化事件的异步流。
+     * @throws {SessionBusyError} 当前会话忙碌时抛出。
+     */
+    runPreparedTask(task: string, prepare: (context: PreparedTaskContext) => Promise<PreparedTaskResult>, options?: {
+        signal?: AbortSignal;
+        role?: PrimaryModelRole;
+    }): AsyncIterable<SessionEvent>;
     /** 单次任务执行主体；调用方 return 的中止与 finally 清理由外层统一协调。 */
     private runOperation;
     /** 幂等销毁：卸载插件后发出 session:end；运行中拒绝，teardown 失败聚合抛出且不完成销毁。 */
     destroy(): Promise<void>;
     private assertIdle;
+    /** 实际请求、静态统计和手动压缩共用目录空间推导；先计正文、工具和非目录提示，再预算整段目录。 */
+    private createPromptAssembler;
+    /** 完整消息提交后完成技能审计；审计失败保留真实历史，停止本轮且不发布成功事件。 */
+    private commitSkills;
+    /** 显式加载仍按同一读取策略、精确缓存与宿主审批裁决；拒绝/取消/审计失败时不追加用户任务。 */
+    private authorizeSkill;
     /**
      * 计算最近一次内部模型请求的上下文占用；无 usage 时显式标注预算估算。
      * run 累计 promptTokens 会重复计算每一步都重发的历史，不能用于窗口占用率。
@@ -2164,4 +2721,4 @@ declare class AgentSession {
     private findClosedToolMessages;
 }
 
-export { AbortError, AgentLoop, type AgentLoopOptions, type AgentPlugin, AgentSession, AnthropicProvider, type AnthropicProviderOptions, type ApprovalChannel, type ApprovalChoice, type ApprovalRequest, type CanonicalMessage, type Capability, type ChatCapabilities, type CommandResult, type ConflictPolicy, type ContentBlock, type ContextBudget, ContextBudgetError, ContextManager, type ContextManagerOptions, ContextOverflowError, type ContextSnapshot, ContextStorageError, type ContextSummary, type ContextUsage, type ContextWindowValue, DEFAULT_CONTEXT_WINDOW_TOKENS, type EventLogger, type ExecutorOptions, FatalError, type FileDetails, FileLogSink, type FileLogSinkOptions, type FileObservation, type HistoryRepair, type HookContext, type HookHandlers, type HookPoint, HookRegistry, type InstructionLoadOptions, type InstructionSnapshot, type InstructionSource, type InteractionBoundary, type InteractionTerminal, JSONLMessageStore, KapibalaError, type LogChannel, type LogEvent, type LogField, type LogInput, type LogLevel, type LogSink, type ManagedSession, type MessageRole, type MessageStore, ModelError, type ModelErrorCategory, type ModelErrorInfo, type ModelErrorOptions, type ModelEvent, type ModelProfile, type ModelProtocol, type ModelProvider, type ModelProviderBinding, type ModelRequest, type ModelRole, type ModelRouter, type NormalizedHistory, OpenAICompatibleProvider, type OpenAIProviderOptions, OpenAIResponsesProvider, type OpenAIResponsesProviderOptions, PathSandbox, type PermissionAction, type PermissionDecision, PermissionPolicy, type PermissionRequest, type PermissionRule, type PluginContext, type PrimaryModelRole, type ProjectIdentity, PromptAssembler, type PromptAssemblerOptions, type ProtocolItemMetadata, type ProtocolOrigin, type ProviderStateBlock, type RedactedThinkingBlock, type RequestPreparation, type ResolvedContextWindow, type RunCommandInput, type RunMetrics, SESSION_SCHEMA_VERSION, SUMMARY_OUTPUT_BUFFER_MULTIPLIER, type SandboxConfig, SessionApprovalCache, SessionBusyError, type SessionConfig, type SessionEvent, type SessionHeader, SessionLock, SessionManager, type SessionManagerOptions, type SessionMetadata, type SessionMode, type SessionRecord, type SessionRecordType, type SessionState, type SessionStats, SessionStore, type ShellDetectOptions, type ShellEnvironment, type ShellKind, type ShellPreference, type ShellScope, SimpleModelRouter, type StatefulMessageStore, type StepLogEntry, type StepLogStage, StructuredLogger, type SummaryCandidate, SummaryService, type SummaryServiceOptions, type TextBlock, type ThinkingBlock, type TokenEstimate, type TokenEstimator, type Tool, type ToolContext, type ToolDecision, type ToolDefinition, ToolError, ToolExecutor, type ToolMetadata, ToolNotFound, ToolRegistry, type ToolResultBlock, type ToolUseBlock, TransportError, type TurnMetrics, UnicodeTokenEstimator, type Usage, assembleCanonicalToolResults, builtinTools, classifyBashOutput, cleanupCommandResults, commandAuditSummary, createContextBudget, createDefaultLogSinks, createLogId, createMessageId, createRunCommandTool, defineTool, describeModelError, detectShell, editFileTool, executionFingerprint, extractFileDetails, globTool, grepTool, identifyHistory, indexInteractions, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, loadInstructions, normalizeHistory, projectSafeFields, readFileTool, recoverIncompleteAudit, renderFileDetails, requestFingerprint, resolveContextWindow, resolveSessionProject, sanitizeModelErrorMessage, sanitizeSessionTitle, stableJsonStringify, stableSerialize, supportsSessionState, toToolDefinition, truncateToolOutput, validateModelBinding, validatePermissionRules, validateSummary, visibleTools, writeFileTool };
+export { AbortError, AgentLoop, type AgentLoopOptions, type AgentPlugin, AgentSession, AnthropicProvider, type AnthropicProviderOptions, type ApprovalChannel, type ApprovalChoice, type ApprovalRequest, type CanonicalMessage, type Capability, type ChatCapabilities, type CommandResult, type ConflictPolicy, type ContentBlock, type ContextBudget, ContextBudgetError, ContextManager, type ContextManagerOptions, ContextOverflowError, type ContextSnapshot, ContextStorageError, type ContextSummary, type ContextUsage, type ContextWindowValue, DEFAULT_CONTEXT_WINDOW_TOKENS, type EventLogger, type ExecutorOptions, FatalError, type FileDetails, FileLogSink, type FileLogSinkOptions, type FileObservation, type HistoryRepair, type HookContext, type HookHandlers, type HookPoint, HookRegistry, type InstructionLoadOptions, type InstructionSnapshot, type InstructionSource, type InteractionBoundary, type InteractionTerminal, JSONLMessageStore, KapibalaError, type LogChannel, type LogEvent, type LogField, type LogInput, type LogLevel, type LogSink, type ManagedSession, type MessageRole, type MessageStore, ModelError, type ModelErrorCategory, type ModelErrorInfo, type ModelErrorOptions, type ModelEvent, type ModelProfile, type ModelProtocol, type ModelProvider, type ModelProviderBinding, type ModelRequest, type ModelRole, type ModelRouter, type NormalizedHistory, OpenAICompatibleProvider, type OpenAIProviderOptions, OpenAIResponsesProvider, type OpenAIResponsesProviderOptions, PathSandbox, type PermissionAction, type PermissionDecision, PermissionPolicy, type PermissionRequest, type PermissionRule, type PluginCommandContribution, type PluginContext, type PluginContribution, PreDispatchError, type PreparedSkill, type PreparedTaskContext, type PreparedTaskResult, type PrimaryModelRole, type ProjectIdentity, PromptAssembler, type PromptAssemblerOptions, type PromptContentSource, type ProtocolItemMetadata, type ProtocolOrigin, type ProviderStateBlock, type RedactedThinkingBlock, type RequestPreparation, type ResolvedContextWindow, type RunCommandInput, type RunMetrics, SESSION_SCHEMA_VERSION, SKILL_LIMITS, SUMMARY_OUTPUT_BUFFER_MULTIPLIER, type SandboxConfig, SessionApprovalCache, SessionBusyError, type SessionConfig, type SessionEvent, type SessionHeader, SessionLock, SessionManager, type SessionManagerOptions, type SessionMetadata, type SessionMode, type SessionRecord, type SessionRecordType, type SessionState, type SessionStats, SessionStore, type ShellDetectOptions, type ShellEnvironment, type ShellKind, type ShellPreference, type ShellScope, SimpleModelRouter, type SkillActivation, type SkillCatalog, type SkillContentSource, type SkillContextState, type SkillDefinition, type SkillDiagnostic, type SkillDocument, type SkillMetadata, type SkillOptions, type SkillQuery, type SkillQueryPage, SkillRegistry, type SkillResourceInput, type SkillResourcePage, type SkillRoot, SkillRuntime, type SkillScanResult, type SkillScope, type StatefulMessageStore, type StepLogEntry, type StepLogStage, StructuredLogger, type SummaryCandidate, SummaryService, type SummaryServiceOptions, type TextBlock, type ThinkingBlock, type TokenEstimate, type TokenEstimator, type Tool, type ToolContext, type ToolDecision, type ToolDefinition, ToolError, type ToolExecutionIdentity, type ToolExecutionResult, ToolExecutor, type ToolHardDenial, type ToolInputValidation, type ToolMetadata, ToolNotFound, ToolRegistry, type ToolRegistrySnapshot, type ToolResultBlock, type ToolResultExecution, type ToolUseBlock, TransportError, type TurnMetrics, UnicodeTokenEstimator, type Usage, assembleCanonicalToolResults, builtinTools, classifyBashOutput, cleanupCommandResults, commandAuditSummary, compareSkillPaths, createContextBudget, createDefaultLogSinks, createLogId, createMessageId, createRunCommandTool, defineTool, 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, toToolDefinition, truncateToolOutput, validateModelBinding, validatePermissionRules, validateSummary, visibleTools, writeFileTool };