@x-otto/hooks 0.0.1-alpha.2 → 0.0.1-alpha.4

package/README.md

@@ -2,19 +2,17 @@
 
 ## Module Purpose
 
-Provides pluggable interception and transformation mechanisms across every stage of the agent lifecycle, with a built-in permission policy system.
+Pluggable interception and transformation engine spanning every stage of the agent lifecycle. Pure hook engine only — the permission policy system, sandbox safety assessment, and failure-signal diagnostics were split out to [`@x-otto/guard`](../guard) (RFC-395).
 
 ## Core Features
 
 | Module                     | Function                                                          |
 | ------------------------ | ------------------------------------------------------------- |
 | HookRegistry             | Registration, priority ordering, and execution engine for 25 hook timings                   |
-| PermissionPolicyRegistry | Permission policy registration and evaluation (allow/deny/escalate)                     |
-| PermissionAuditLog       | Audit trail for permission decisions                                              |
-| PermissionGuardHook      | Permission → tool:guard integration                                       |
-| Built-in Policies        | FILE_GUARD / DESTRUCTIVE_COMMAND / mode policy / freeze / allow/deny lists |
-| Presets                  | 4 permission modes: default / strict / minimal / none |
-| 13 Built-in Hooks        | session / tool guard / transform / quality / stream / compaction    |
+| defineHook               | Type-inferred hook factory (timing literal drives handle signature)              |
+| HOOK_NODES               | Single source of truth for the 25 timings + compile-time drift guard             |
+| Presets                  | 4 tiers: default / strict / minimal / none |
+| Built-in Hooks           | session / tool guard / transform / quality / stream / compaction (infrastructure + agent-hygiene hooks) |
 
 ## Hook Timings (25 total, single-source HOOK_NODES)
 
@@ -35,44 +33,42 @@ import { createHookRegistry, defineHook } from '@x-otto/hooks'
 
 const registry = createHookRegistry({ preset: 'default' })
 
-// Register a tool-execution permission guard
+// Register a tool-execution interceptor
 registry.register(
   defineHook({
-    name: 'file-write-guard',
+    name: 'my-tool-guard',
     timing: 'tool.execute.before',
     priority: 0,
     handle: (input, output) => {
-      if (input.toolName === 'write' && input.params.path?.includes('/etc/')) {
-        output.decision = 'deny'
-        output.decisionReason = 'Writing to /etc/ is blocked'
+      if (input.toolName === 'write' && String(input.args.path ?? '').includes('/etc/')) {
+        output.cancelled = true
+        output.cancelReason = 'Writing to /etc/ is blocked'
       }
     },
   }),
 )
 ```
 
+For permission policies, sandbox safety, and failure diagnostics, see [`@x-otto/guard`](../guard).
+
 ## Directory Overview
 
 ```
 src/
-  types.ts                  # core types
-  hook-registry.ts          # hook registration and execution
-  permission/
-    permission-policy-registry.ts
-    permission-audit-log.ts
-    permission-guard-hook.ts
-    builtin-policies.ts
-    presets.ts
-  builtin-hooks/
-    session/                # 6 session hooks
-    tool-guard/             # 6 tool-guard hooks
-    transform/               # 4 transform hooks
-    quality/                # 3 quality hooks
-    stream/                 # 2 stream hooks
-    compaction/              # 2 compaction hooks
-    background/              # 2 background hooks
+  types.ts                  # re-exports @x-otto/hook-contracts timing/payload types
+  hook-nodes.ts             # HOOK_NODES single source of truth + drift guard
+  hook-spec.ts              # defineHook factory + HookSpec
+  hook-registry.ts          # hook registration + execution engine + 4-tier HookPreset
+  core/
+    hook-state.ts           # per-session state container
+    session/                # session hooks (first-message-variant)
+    tool-guard/             # tool-guard hooks (label/output truncation / error tracking)
+    transform/              # transform hooks (thinking-validator / anthropic-effort / token-budget)
+    quality/                # quality hooks (comment-checker)
+    stream/                 # stream hooks (stream-metrics)
+    compaction/             # compaction hooks (compaction-logger)
   index.ts
-tests/                      # 9 test files
+tests/                      # 9 test files (engine + built-in hooks)
 ```
 
 ## Development Commands
@@ -85,4 +81,4 @@ pnpm --filter @x-otto/hooks clean
 
 ## Related Packages
 
-`@x-otto/shared`, `@x-otto/env`
+`@x-otto/hook-contracts` (timing/payload type contracts), `@x-otto/guard` (permission/sandbox/observability — depends on this package), `@x-otto/shared`, `@x-otto/env`

package/dist/index.d.ts

@@ -1,5 +1,33 @@
-import { ChatMessageInput, ChatMessageOutput, ChatParamsInput, ChatParamsOutput, HookEmitInput, HookHandle, HookInput, HookOutput, HookPayloadMap, HookTiming, InterceptorTiming, MessagesTransformInput, MessagesTransformOutput, ObserverTiming, PermissionMode, PermissionPolicySetting, PermissionRuleConfig, RuleEffect, RuleEffect as RuleEffect$1, SessionEventInput, SystemPromptTransformInput, SystemPromptTransformOutput, ToolExecuteAfterInput, ToolExecuteAfterOutput, ToolExecuteBeforeInput, ToolExecuteBeforeOutput } from "@x-otto/hook-contracts";
+import { ChatMessageInput, ChatMessageOutput, ChatParamsInput, ChatParamsOutput, HookAbortSignal, HookAbortSignal as HookAbortSignal$1, HookEmitInput, HookHandle, HookInput, HookOutput, HookPayloadMap, HookTiming, InterceptorTiming, MessagesTransformInput, MessagesTransformOutput, ObserverTiming, SessionEventInput, SystemPromptTransformInput, SystemPromptTransformOutput, ToolExecuteAfterInput, ToolExecuteAfterOutput, ToolExecuteBeforeInput, ToolExecuteBeforeOutput, WATERFALL_TIMINGS, WaterfallTiming, isWaterfallTiming } from "@x-otto/hook-contracts";
 
+//#region src/hook-spec.d.ts
+type BaseRuntimeHook = {
+  name: string;
+  timing: HookTiming;
+  priority: number;
+  enabled: boolean;
+};
+type ObserverRuntimeHook = BaseRuntimeHook & {
+  kind: 'observer';
+  handle: (input: unknown) => void | Promise<void>;
+};
+type InterceptorRuntimeHook = BaseRuntimeHook & {
+  kind: 'interceptor';
+  handle: (input: unknown, output: unknown) => void | HookAbortSignal$1 | Promise<void | HookAbortSignal$1>;
+};
+type HookSpec = ObserverRuntimeHook | InterceptorRuntimeHook;
+/**
+ * 所有 as 强转集中在此处：HookHandle<T> 因函数参数逆变无法自动赋给 (unknown) => void。
+ * factory 函数通过 timing 字面量驱动 handle 的类型推断，调用侧零 cast。
+ */
+declare function defineHook<T extends HookTiming>(config: {
+  name: string;
+  timing: T;
+  handle: HookHandle<T>;
+  priority?: number;
+  enabled?: boolean;
+}): HookSpec;
+//#endregion
 //#region src/core/hook-state.d.ts
 interface StreamMetrics {
   startTime: number;
@@ -27,33 +55,33 @@ declare class HookState {
   clearSession(sessionId: string): void;
 }
 //#endregion
-//#region src/hook-spec.d.ts
-type BaseRuntimeHook = {
-  name: string;
-  timing: HookTiming;
-  priority: number;
-  enabled: boolean;
-};
-type ObserverRuntimeHook = BaseRuntimeHook & {
-  kind: 'observer';
-  handle: (input: unknown) => void | Promise<void>;
-};
-type InterceptorRuntimeHook = BaseRuntimeHook & {
-  kind: 'interceptor';
-  handle: (input: unknown, output: unknown) => void | Promise<void>;
-};
-type HookSpec = ObserverRuntimeHook | InterceptorRuntimeHook;
+//#region src/hook-preset.d.ts
+type HookPreset = 'default' | 'strict' | 'minimal' | 'none';
+//#endregion
+//#region src/scope.d.ts
 /**
- * 所有 as 强转集中在此处：HookHandle<T> 因函数参数逆变无法自动赋给 (unknown) => void。
- * factory 函数通过 timing 字面量驱动 handle 的类型推断，调用侧零 cast。
+ * RFC-395 M4：scoped registration 的 disposable 契约。token 由 `HookRegistry.register()`
+ * / `registerAll()` 返回，`dispose()` 精确移除该次注册（按 spec 引用），与 `unregister(name)`
+ * 的按名移除互补。现有调用方（忽略返回值）行为不变。
  */
-declare function defineHook<T extends HookTiming>(config: {
-  name: string;
-  timing: T;
-  handle: HookHandle<T>;
-  priority?: number;
-  enabled?: boolean;
-}): HookSpec;
+interface Disposable {
+  dispose(): void;
+}
+/**
+ * RFC-395 M4：具名子 scope——`HookRegistry.createScope(name)` 创建。scope 内的注册
+ * 自动带 `${name}:` 前缀（与 RFC-216 插件分桶的 `plugin:${pluginId}:` 命名约定同构），
+ * `dispose()` 批量撤销 scope 内全部注册。与插件分桶共存：token 优先，分桶兜底。
+ */
+declare class HookScope implements Disposable {
+  private readonly registry;
+  private readonly name;
+  private readonly tokens;
+  constructor(registry: HookRegistry, name: string);
+  /** 带 `${name}:` 前缀注册；返回精确 token（dispose 只移除本次注册）。 */
+  register(spec: HookSpec): Disposable;
+  /** 批量撤销 scope 内全部注册（token 幂等：已被外部 unregister 的 token 是 no-op）。 */
+  dispose(): void;
+}
 //#endregion
 //#region src/hook-registry.d.ts
 interface RegisteredHookInfo {
@@ -62,7 +90,6 @@ interface RegisteredHookInfo {
   priority: number;
   enabled: boolean;
 }
-type HookPreset = 'default' | 'strict' | 'minimal' | 'none';
 interface HookRegistryOptions {
   preset?: HookPreset;
   /** RFC-153 D1：interceptor/observer hook 超时时的旁路通知（可选，宿主层注入）。
@@ -80,8 +107,15 @@ declare class HookRegistry {
   private readonly onHookTimeout?;
   readonly state: HookState;
   constructor(options?: HookRegistryOptions);
-  register(spec: HookSpec): void;
-  registerAll(specs: HookSpec[]): void;
+  /**
+   * RFC-395 M4：返回精确 token（dispose 按 spec 引用移除本次注册，不误伤同名 hook）。
+   * 现有调用方忽略返回值即可，行为不变。
+   */
+  register(spec: HookSpec): Disposable;
+  /** RFC-395 M4：批量注册，返回一一对应的 token 数组（与 register 同语义）。 */
+  registerAll(specs: HookSpec[]): Disposable[];
+  /** RFC-395 M4：具名子 scope——scope 内注册自动带 `${name}:` 前缀，dispose 批量撤销。 */
+  createScope(name: string): HookScope;
   on<T extends HookTiming>(timing: T, name: string, handle: HookHandle<T>, priority?: number): this;
   has(name: string): boolean;
   unregister(name: string): boolean;
@@ -89,33 +123,6 @@ declare class HookRegistry {
   enable(name: string): void;
   getRegistered(timing?: HookTiming): RegisteredHookInfo[];
   execute<T extends InterceptorTiming>(timing: T, input: HookInput<T>, output: HookOutput<T>): Promise<void>;
-  /**
-   * RFC-153 D1：interceptor hooks 挂起兜底——`execute()` 循环内此前是裸 `await hook.handle(...)`，
-   * 挂起（无限循环/无限 fetch/死锁）的 hook 会永久阻塞整个 agent turn。复用 observer 路径
-   * （`runObserverHookWithTimeout`）已验证的 `Promise.race` + `unref()` 模式，阈值改用两路径共享的
-   * `HOOK_TIMEOUT_MS` 常量（规则 1：超时不等于中止——不承诺真正终止 hook 内部执行）。
-   * 超时命中时通过 `onHookTimeout` 回调向上冒泡（规则 7：只携带领域无关字段，`packages/hooks`
-   * 不认识"插件"概念），调用方（`packages/coding`）负责解析 hookName 里的 pluginId 前缀。
-   */
-  private runInterceptorWithTimeout;
-  /**
-   * RFC-143 M0：observer hook 挂起兜底。`emit()` 此前的 try/catch 只吞同步抛错和 rejected
-   * promise，不吞「handler 挂起」（无限循环/无限 fetch/死锁）——`await hook.handle(input)` 会
-   * 无限期阻塞调用方（如用户显式 `removeSession`、task 生命周期判定、流式启动）。
-   * 超时阈值使用与 interceptor 路径（`runInterceptorWithTimeout`）共享的模块级常量
-   * `HOOK_TIMEOUT_MS`（RFC-153 D1：避免两条路径各自维护一份可能漂移的数字，此前本方法
-   * 独立持有的 `EMIT_TIMEOUT_MS` 已废弃合并）。`unref()` 避免这个定时器阻塞进程退出。
-   */
-  private runObserverHookWithTimeout;
-  /**
-   * RFC-143 R2a：`session.error` timing 的 input 契约上携带原始 `Error` 对象
-   * （`HookPayloadMap['session.error'].input.error: Error`，见 hook-contracts/timings.ts）。
-   * SDK 层（`module-wiring.ts`）已对 definePlugin 消费路径做 `error.message` 转换，但那只是
-   * 单一消费方的自觉行为——emit() 是所有 observer hook（含非 SDK 注册路径，如未来的引擎内部
-   * 钩子/测试工具）的唯一入口，必须在这里做结构式 sanitize，防止任何消费方读到含栈追踪/敏感
-   * 路径信息的原始 Error 对象。sanitize 后的 input 只对 `session.error` 生效，其余 timing 原样传递。
-   */
-  private sanitizeEmitInput;
   emit<T extends ObserverTiming>(timing: T, input: HookEmitInput<T>): Promise<void>;
   clear(): void;
   private getSortedInterceptorHooks;
@@ -166,382 +173,5 @@ declare function createStreamEndMetricsHook(state: HookState): HookSpec;
 declare function createCompactionLoggerHook(state: HookState): HookSpec;
 declare function createCompactionAfterHook(state: HookState): HookSpec;
 //#endregion
-//#region src/core/edit-files-panel.d.ts
-/** 编辑文件记录的内部类型（hooks 层使用，不耦合 tui 的 EditedFileEntry）。 */
-interface EditFileInfo {
-  path: string;
-  operation: 'edit' | 'write' | 'delete';
-  oldContent?: string;
-  newContent?: string;
-  addedLines: number;
-  removedLines: number;
-  timestamp: number;
-  toolCallId: string;
-}
-/** 文件修改回调（CLI 层负责适配到 TuiHandle.addEditedFile） */
-type EditFileCallback = (info: EditFileInfo) => void;
-interface EditFilesPanelHookOptions {
-  onFileEdited?: EditFileCallback;
-  /** 延迟获取回调——用于注册时 TUI 尚未就绪的场景（取值时机=emit 时而非 register 时）。优先级高于 onFileEdited。 */
-  getOnFileEdited?: () => EditFileCallback | undefined;
-  dedupCache?: Set<string> | null;
-}
-/**
- * 创建 hook spec，注册后在每次 edit/write 工具执行完成后累积回写 TUI。
- *
- * 用法：
- *   const hook = createEditFilesPanelHook({
- *     onFileEdited: (info) => tuiHandle.addEditedFile({
- *       ...info,
- *       addedLines: info.addedLines,
- *       removedLines: info.removedLines,
- *       turnId: currentTurnId,
- *     }),
- *   })
- *   hookRegistry.register(hook)
- */
-declare function createEditFilesPanelHook(options?: EditFilesPanelHookOptions): HookSpec;
-//#endregion
-//#region src/core/permission/types.d.ts
-interface PolicyScope {
-  /** 适用的 agent 名称, '*' 或缺省表示所有 */
-  agents?: string[];
-  sessions?: string[];
-}
-interface PermissionContext {
-  timing: HookTiming;
-  toolName: string;
-  args: Record<string, unknown>;
-  agentName: string;
-  sessionId: string;
-  filePath?: string;
-  metadata: Record<string, unknown>;
-}
-interface RuleMatch {
-  tools?: string[];
-  paths?: RegExp[];
-  /** 必须同步。 */
-  condition?: (context: PermissionContext) => boolean;
-}
-interface PermissionRule {
-  name: string;
-  effect: RuleEffect$1;
-  match: RuleMatch;
-  denyReason?: string;
-  askPrompt?: string;
-  /**
-   * 兜底规则（C1/RFC-016）：true 表示本规则仅在**没有任何非兜底规则命中**时生效
-   * （如 strict 的 deny-unmatched、readonly 的 deny-writes 这类 match:{} 默认拒绝）。
-   * 在 deny-wins 评估下,兜底 deny 不得盖过显式 allow（否则 strict/readonly 自破）。
-   */
-  fallthrough?: boolean;
-}
-interface PermissionPolicy {
-  name: string;
-  priority: number;
-  enabled: boolean;
-  scope: PolicyScope;
-  rules: PermissionRule[];
-  /**
-   * 安全护栏标记（C1/RFC-016）：true 表示本策略的 ask/deny 是安全护栏
-   * （受保护路径、破坏性命令），alwaysAllow 绝不升级其 ask，bypass 也不能盖过。
-   * 缺省 false（mode/user 策略的 ask 可被 alwaysAllow 升级）。
-   */
-  safety?: boolean;
-}
-interface PermissionDecision {
-  effect: RuleEffect$1;
-  policyName: string;
-  ruleName: string;
-  reason?: string;
-  timestamp: number;
-  evaluatedPolicies: number;
-  /**
-   * 命中策略的安全护栏位（透传自 PermissionPolicy.safety）——HITL 风险等级单一真源（RFC-077 M3）。
-   * 取代 riskFromDecision 靠正则匹配 policyName 子串(destructive|credential|file-guard)反推风险的
-   * 字符串考古：自定义安全策略名不含三魔词时不再被误判为 medium。仅 ask/deny（经 pick）携带；
-   * allow/默认放行不参与风险评估故可空。
-   */
-  safety?: boolean;
-}
-interface PermissionAuditEntry {
-  timestamp: number;
-  sessionId: string;
-  agentName: string;
-  toolName: string;
-  filePath?: string;
-  decision: PermissionDecision;
-}
-//#endregion
-//#region src/core/permission/builtin-policies.d.ts
-interface PermissionToolDescriptor {
-  name: string;
-  readonly?: boolean;
-  metadata?: {
-    category?: string;
-  };
-}
-interface PermissionToolSets {
-  readonlyTools: Set<string>;
-  writeTools: Set<string>;
-  fileWriteTools: Set<string>;
-}
-interface PermissionToolSetsInput {
-  readonlyTools?: Iterable<string>;
-  writeTools?: Iterable<string>;
-  fileWriteTools?: Iterable<string>;
-}
-declare function createPermissionToolSetsFromRegistry(tools: Iterable<PermissionToolDescriptor>): PermissionToolSets;
-declare function createFileGuardPolicy(toolSets?: PermissionToolSetsInput): PermissionPolicy;
-declare const DESTRUCTIVE_COMMAND_POLICY: PermissionPolicy;
-declare const CREDENTIAL_READ_POLICY: PermissionPolicy;
-declare function createOttoStateDomainPolicy(toolSets?: PermissionToolSetsInput): PermissionPolicy;
-declare function createEgressAllowlistPolicy(allowedHosts: readonly string[]): PermissionPolicy;
-declare function createDisabledToolsPolicy(disabledTools: string[]): PermissionPolicy;
-declare function createPermissionModePolicy(mode: PermissionMode, toolSets?: PermissionToolSetsInput): PermissionPolicy;
-//#endregion
-//#region src/core/permission/register-builtin.d.ts
-interface RegisterBuiltinPoliciesOptions {
-  toolSets?: PermissionToolSetsInput;
-}
-//#endregion
-//#region src/core/permission/policy-registry.d.ts
-declare class PermissionPolicyRegistry {
-  private policies;
-  /**
-   * 项目级「始终允许」的工具名（R8-B base）。语义：把该工具被评估出的 `ask` 升级为 `allow`，
-   * 但绝不把 `deny` 改为 allow——安全 deny（受保护路径/破坏性命令）始终优先。
-   * 来源 .otto/config.json，对工作区所有会话生效（手动配置的常驻放行基线）。
-   */
-  private alwaysAllow;
-  /**
-   * 会话级「始终允许」（弹窗里点「始终允许」的运行时授权）：按 sessionId 隔离，
-   * 跟随会话持久化（落盘进 session 记录，--continue 时回灌），互不串味——
-   * 一次性的信任决策不再泄漏到项目其它会话/永久污染 config（修旧 R8-B 全局泄漏）。
-   */
-  private sessionAlwaysAllow;
-  setAlwaysAllow(tools: readonly string[]): void;
-  addAlwaysAllow(tool: string): void;
-  getAlwaysAllow(): string[];
-  /** 整体替换某会话的 always-allow 集合（会话恢复/回灌用）。空集合=移除该会话条目。 */
-  setSessionAlwaysAllow(sessionId: string, tools: readonly string[]): void;
-  addSessionAlwaysAllow(sessionId: string, tool: string): void;
-  /** 不含项目级基线。 */
-  getSessionAlwaysAllow(sessionId: string): string[];
-  clearSessionAlwaysAllow(sessionId: string): void;
-  register(policy: PermissionPolicy): void;
-  registerAll(policies: PermissionPolicy[]): void;
-  unregister(name: string): boolean;
-  has(name: string): boolean;
-  /**
-   * collect-all / deny-wins（C1/RFC-016，收集全部命中规则后按 effect 优先级裁决）：
-   * 收集所有命中规则,决策优先级 deny > ask > allow,**与命中/优先级顺序无关**——
-   * priority 仅用于在同 effect 内择 reason。这样 `bypass` 的 allow-all 不再能盖过
-   * 安全护栏的 deny/ask（first-match 旧语义的倒置缺口）。
-   *
-   * alwaysAllow（R8-B）：仅升级**非安全护栏**的 ask→allow;安全护栏（file-guard/
-   * destructive-guard，policy.safety=true）的 ask/deny 绝不被升级或盖过。
-   */
-  evaluate(context: PermissionContext): PermissionDecision;
-  getEffective(agentName: string): PermissionPolicy[];
-  getAll(): PermissionPolicy[];
-  clear(): void;
-}
-declare function createPermissionRegistry(options?: RegisterBuiltinPoliciesOptions): PermissionPolicyRegistry;
-declare function compilePolicyFromSetting(setting: PermissionPolicySetting): PermissionPolicy;
-//#endregion
-//#region src/core/permission/audit-log.d.ts
-declare class PermissionAuditLog {
-  private entries;
-  private readonly maxEntries;
-  constructor(maxEntries?: number);
-  record(context: PermissionContext, decision: PermissionDecision): void;
-  getEntries(filter?: {
-    sessionId?: string;
-    effect?: RuleEffect;
-  }): PermissionAuditEntry[];
-  getDenyCount(sessionId?: string): number;
-  getAskCount(sessionId?: string): number;
-  clear(sessionId?: string): void;
-  get size(): number;
-}
-//#endregion
-//#region src/core/permission/permission-guard.d.ts
-declare class PermissionGuardHook {
-  readonly name = "permission-guard";
-  readonly timing: "tool.execute.before";
-  readonly priority = 5;
-  enabled: boolean;
-  private readonly registry;
-  private readonly auditLog?;
-  constructor(registry: PermissionPolicyRegistry, auditLog?: PermissionAuditLog);
-  handle: (input: ToolExecuteBeforeInput, output: ToolExecuteBeforeOutput) => void;
-}
-declare function createPermissionGuardHook(registry: PermissionPolicyRegistry, auditLog?: PermissionAuditLog): HookSpec;
-//#endregion
-//#region src/core/permission/baseline-provisioning.d.ts
-/**
- * RFC-077 M3-B：bare-runtime（无工具注册表）的基线 `fileWriteTools`——`createFileGuardPolicy`
- * 的 protect-system-paths 规则按 `tools: [...fileWriteTools]` 过滤，无注册表派生集时须给默认，
- * 否则空集 → 该规则匹配不到任何工具 → protected-path 写不被拦。
- *
- * 与 standalone `createFileGuardHook` 的 `WRITE_TOOLS` 同源（canonical otto 文件写工具）；bash 非
- * path-based 故不入 fileWriteTools（其命令面由 destructive/credential 命令策略覆盖）。**宿主有工具
- * 注册表时经 `createPermissionToolSetsFromRegistry` 派生集覆盖本默认**（coding 走该路径）。
- */
-declare const BASELINE_PERMISSION_TOOL_SETS: PermissionToolSetsInput;
-/**
- * RFC-077 M3-B（D6 §4.11「安全护栏先 provision 再删」）：把权限策略引擎 + 基线安全策略
- * （file-guard / credential / destructive，经 `createPermissionRegistry` 注册）下沉为 bare-runtime
- * 的**默认提供**——注册 permission-guard hook（`tool.execute.before`），让无宿主 PermissionController
- * 的裸运行时也 safe-by-default（安全是引擎核心能力，非宿主可选项）。
- *
- * **幂等**：宿主（coding）已注册 permission-guard 时直接返回，绝不双注册——bare 分支与宿主
- * provision 二选一（createAgentRuntime 仅在自建 hookRegistry、未被宿主注入时调用本函数）。
- *
- * @returns 新建的基线 registry（宿主已 provision 时返回 undefined）。
- */
-declare function provisionBaselineSecurity(hookRegistry: HookRegistry): PermissionPolicyRegistry | undefined;
-//#endregion
-//#region src/core/permission/always-allow.d.ts
-/**
- * 条目是否格式良好——供 `/permissions add` 校验，拒绝静默持久化危险/无意义条目。
- * 合法：`tool`（整工具）或 `tool(非空 content)`。
- * 非法：空串、空括号 `tool()`（读法似"无参"实为整工具,塌缩陷阱,RFC-073 P3）、
- *       括号不平衡/含元字符的垃圾（`bash(((`、`a b`）。
- */
-declare function isWellFormedAllowEntry(raw: string): boolean;
-/**
- * 为「始终允许」按钮派生一个 bash 命令前缀（程序名 + 子命令两段），供 UI 显式呈现 +
- * 持久化为 `bash(<prefix>)`。复合/混淆/env 赋值命令返回 null → 调用方回退整工具放行
- * （此时安全护栏仍 bypass-immune，不会因整工具放行而漏过危险叶子）。
- *
- * 例：`git status -s`→`git status`、`npm run build`→`npm run`、`ls -la`→`ls`、
- * `cd /x && git status`→`git status`、`a && b`/`$()`/`FOO=1 cmd`→null。
- */
-declare function bashAlwaysAllowPrefix(command: string): string | null;
-//#endregion
-//#region src/core/permission/command-canonicalize.d.ts
-/**
- * 从一条 bash 命令启发式提取**写入目标路径**（M4 Phase 2 前置 / C2 加固）。
- *
- * bash 无 pathParams,沙箱 assess 看不到 shell 写目标 → 默认开会让越界 bash 写硬失败。
- * 本函数解析每个子片段的写向量,喂给 assess 以便升级为 ask 而非硬失败：
- *   - 重定向 `> f` `>> f` `2> f` `&> f` `>| f`
- *   - `tee [-a] f...`、`cp/mv/install/ln ... dst`、`dd of=f`、`touch/rm/rmdir/mkdir f...`
- * 启发式（非 tree-sitter）：覆盖常见形态;复杂引用/变量间接漏网者仍由沙箱兜底（硬失败,
- * 不弱于现状）。返回去重路径（相对/绝对原样,由 assess 解析）。
- */
-declare function extractWriteTargets(command: string): string[];
-//#endregion
-//#region src/sandbox-safety.d.ts
-type SandboxVerdict = 'auto-allow' | 'ask' | 'deny';
-interface SandboxAssessment {
-  verdict: SandboxVerdict;
-  reason?: string;
-}
-interface SandboxOp {
-  writePaths?: readonly string[];
-  network?: boolean;
-}
-interface SandboxAssessContext {
-  mode: PermissionMode;
-  projectRoot: string;
-  writableRoots: readonly string[];
-  deniedRoots: readonly string[];
-  networkAllowed: boolean;
-  /**
-   * bash 沙箱越界自动放行开关（opt-in，默认 false，见 SandboxConfig.autoAllowBashIfSandboxed）。
-   * 本字段只是透传给 sandbox-guard hook 消费——assessSandboxSafety 本身不读取它（保持纯函数
-   * 决策矩阵不变），由 sandbox-guard 在拿到 'ask' verdict 后结合此字段 + 权限层已有裁决
-   * （output.decision）判断是否降级为自动放行。
-   */
-  autoAllowBashIfSandboxed?: boolean;
-}
-declare function assessSandboxSafety(op: SandboxOp, ctx: SandboxAssessContext): SandboxAssessment;
-declare function defaultDeniedRoots(workspaceDir: string, homeDir: string): string[];
-/**
- * 默认可写根：projectRoot + os.tmpdir() + 字面 `/tmp`。
- *
- * 参照 codex（openai/codex codex-rs/protocol/src/permissions.rs
- * legacy_runtime_file_system_policy_for_cwd）：SlashTmp 与 Tmpdir 是两个独立的默认可写
- * special path，同时生效（`exclude_slash_tmp`/`exclude_tmpdir_env_var` 默认均 false）。
- * macOS 上 `os.tmpdir()` 落在 `/var/folders/...`（进程级临时目录），与用户/shell 习惯手写的
- * 字面 `/tmp`（→ 真实路径 `/private/tmp`，全系统共享临时目录）是两棵不同的目录树——只信
- * os.tmpdir() 会让 `mkdir -p /tmp/xxx` 这类零风险操作被误判越界触发审批（见 sandbox-guard
- * 越界升级事故复盘）。underAny() 的 realpath 归一化解决的是"同一路径不同书写形式"，本条解决
- * 的是"两个本就不同的物理临时目录都该被信任"。
- */
-declare function computeSandboxRoots(mode: PermissionMode, projectRoot: string, tmpDir: string, extra?: readonly string[]): string[];
-//#endregion
-//#region src/observability/failure-signals.d.ts
-type FailureSignalKind = 'tool-error' | 'permission-denied';
-interface FailureSignal {
-  kind: FailureSignalKind;
-  /** 聚合签名（如 toolName）——同签名复发即累加。 */
-  signature: string;
-  count: number;
-  firstSeen: number;
-  lastSeen: number;
-  /** 最近一次的简短细节（如错误首行，截断）。 */
-  detail?: string;
-}
-/** 跨会话失败信号存储：按 (kind,signature) 聚合计数。诊断据此只认硬信号。 */
-declare class FailureSignalStore {
-  private readonly signals;
-  private readonly clock;
-  constructor(clock?: () => number);
-  record(kind: FailureSignalKind, signature: string, detail?: string): void;
-  /** 复发达阈值（默认 ≥3）的信号，按计数降序——诊断只在这些硬信号上提案。 */
-  recurring(minCount?: number): FailureSignal[];
-  all(): FailureSignal[];
-  clear(): void;
-}
-/** RFC-026 阶段3：tool.execute.after 把工具 isError 记成结构化失败信号。 */
-declare function createFailureSignalHook(store: FailureSignalStore): HookSpec;
-/**
- * RFC-067 M121-04a：把**权限拒绝**记成 `permission-denied` 失败信号（补 FailureSignalKind 的另一半，
- * 此前从无 caller 记录此 kind）。
- *
- * 为何在 tool.execute.before：denied 工具在 tool-executor 早返（errorKind:'permission'），**绕过
- * tool.execute.after**，故 after-hook（createFailureSignalHook）看不到它。权限/沙箱守卫在 before 层
- * 设 `output.decision='deny'`（如 sandbox-guard pri 6），所有 before-hook 跑完才判 deny 裁决——故本
- * recorder 用**晚 priority（90）**确保跑在守卫之后、读到累积的 decision。
- */
-declare function createPermissionDenyHook(store: FailureSignalStore): HookSpec;
-//#endregion
-//#region src/observability/diagnoser.d.ts
-interface Proposal {
-  /** 稳定 id（= kind:signature，便于去重）。 */
-  id: string;
-  signature: string;
-  kind: 'investigate-fix';
-  /** 改进指令（L1：用户审后可 /job 执行；诊断器**不**自动跑）。 */
-  directive: string;
-  /** 来源证据（provenance）：哪个信号、复发几次、细节。 */
-  evidence: {
-    signalKind: FailureSignal['kind'];
-    count: number;
-    detail?: string;
-  };
-  createdAt: number;
-}
-interface DiagnoserConfig {
-  /** 复发阈值（信号 count ≥ 此才提案；默认 3）。 */
-  minCount?: number;
-  clock?: () => number;
-}
-declare class Diagnoser {
-  private readonly signals;
-  private readonly proposed;
-  private readonly minCount;
-  private readonly clock;
-  constructor(signals: FailureSignalStore, config?: DiagnoserConfig);
-  /** 扫硬信号（recurring ≥ minCount）→ **新**提案（已提过的签名跳过，防风暴）。 */
-  propose(): Proposal[];
-  /** 重置去重（用户处理完想重新评估时）。 */
-  reset(): void;
-}
-//#endregion
-export { BASELINE_PERMISSION_TOOL_SETS, CREDENTIAL_READ_POLICY, type ChatMessageInput, type ChatMessageOutput, type ChatParamsInput, type ChatParamsOutput, type CompactionStats, DESTRUCTIVE_COMMAND_POLICY, Diagnoser, type DiagnoserConfig, type EditFileCallback, type EditFileInfo, type EditFilesPanelHookOptions, type FailureSignal, type FailureSignalKind, FailureSignalStore, type HookHandle, type HookInput, type HookOutput, type HookPayloadMap, type HookPreset, HookRegistry, type HookRegistryOptions, type HookSpec, HookState, type HookTiming, type InterceptorTiming, type MessagesTransformInput, type MessagesTransformOutput, type ObserverTiming, type PermissionAuditEntry, PermissionAuditLog, type PermissionContext, type PermissionDecision, PermissionGuardHook, type PermissionMode, type PermissionPolicy, PermissionPolicyRegistry, type PermissionPolicySetting, type PermissionRule, type PermissionRuleConfig, type PermissionToolDescriptor, type PermissionToolSets, type PermissionToolSetsInput, type PolicyScope, type Proposal, type RuleEffect, type RuleMatch, type SandboxAssessContext, type SandboxAssessment, type SandboxOp, type SandboxVerdict, type SessionEventInput, type StreamMetrics, type SystemPromptTransformInput, type SystemPromptTransformOutput, type TokenBudgetConfig, type ToolErrorRecord, type ToolErrorTrackerConfig, type ToolExecuteAfterInput, type ToolExecuteAfterOutput, type ToolExecuteBeforeInput, type ToolExecuteBeforeOutput, assessSandboxSafety, bashAlwaysAllowPrefix, compilePolicyFromSetting, computeSandboxRoots, createAnthropicEffortHook, createCommentCheckerHook, createCompactionAfterHook, createCompactionLoggerHook, createDisabledToolsPolicy, createEditFilesPanelHook, createEgressAllowlistPolicy, createFailureSignalHook, createFileGuardPolicy, createFirstMessageVariantHook, createHookRegistry, createLabelTruncatorHook, createOttoStateDomainPolicy, createOutputTruncationHook, createPermissionDenyHook, createPermissionGuardHook, createPermissionModePolicy, createPermissionRegistry, createPermissionToolSetsFromRegistry, createStreamEndMetricsHook, createStreamMetricsHook, createThinkingValidatorHook, createTokenBudgetHook, createToolErrorTrackerHook, defaultDeniedRoots, defineHook, extractWriteTargets, isWellFormedAllowEntry, provisionBaselineSecurity };
+export { type ChatMessageInput, type ChatMessageOutput, type ChatParamsInput, type ChatParamsOutput, type CompactionStats, type Disposable, type HookAbortSignal, type HookHandle, type HookInput, type HookOutput, type HookPayloadMap, type HookPreset, HookRegistry, type HookRegistryOptions, HookScope, type HookSpec, HookState, type HookTiming, type InterceptorTiming, type MessagesTransformInput, type MessagesTransformOutput, type ObserverTiming, type SessionEventInput, type StreamMetrics, type SystemPromptTransformInput, type SystemPromptTransformOutput, type TokenBudgetConfig, type ToolErrorRecord, type ToolErrorTrackerConfig, type ToolExecuteAfterInput, type ToolExecuteAfterOutput, type ToolExecuteBeforeInput, type ToolExecuteBeforeOutput, WATERFALL_TIMINGS, type WaterfallTiming, createAnthropicEffortHook, createCommentCheckerHook, createCompactionAfterHook, createCompactionLoggerHook, createFirstMessageVariantHook, createHookRegistry, createLabelTruncatorHook, createOutputTruncationHook, createStreamEndMetricsHook, createStreamMetricsHook, createThinkingValidatorHook, createTokenBudgetHook, createToolErrorTrackerHook, defineHook, isWaterfallTiming };
 //# sourceMappingURL=index.d.ts.map