@s_s/agent-kit 1.0.0 → 1.2.0

package/README.md

@@ -6,7 +6,7 @@ MCP Server / Skill 开发基础设施库。提供 agent 检测、prompt 注入
 
 - **Agent 检测** — 通过文件系统特征或 MCP clientInfo 自动识别 agent 类型（OpenCode、Claude Code、OpenClaw、Codex）
 - **Prompt 注入** — 向 agent 配置文件（`AGENTS.md`、`CLAUDE.md`、manifests 等）注入自定义指令，支持幂等更新
-- **Intent-based Hook 系统** — 按意图声明，自动翻译为各 agent 原生格式，支持三层优先级和显式降级
+- **Hook 安装** — 用户提供完整 hook 内容，agent-kit 负责写入正确路径、管理 settings.json 和生命周期
 - **跨平台数据目录** — 自动适配 macOS / Linux / Windows，支持 global / project 两种作用域
 - **零运行时依赖** — 纯 TypeScript，零 dependencies
 - **工厂模式** — `createKit(name)` 返回绑定了工具名的函数集，支持解构，无全局状态
@@ -20,42 +20,52 @@ npm install @s_s/agent-kit
 ## 快速开始
 
 ```typescript
-import { createKit, hooks, detectAgent } from '@s_s/agent-kit';
+import { createKit, defineHooks, detectAgent } from '@s_s/agent-kit';
 
-// 1. 创建 kit 实例（支持解构）
+// 1. 创建 kit 实例
 const { injectPrompt, installHooks, getDataDir } = createKit('my-mcp');
 
-// 2. 声明 hook 意图（全局 API，不绑定实例）
-hooks.inject({
-  perTurn: 'Remember to use my-mcp tools when relevant.',
-  sessionStart: 'Welcome! Check my-mcp for context.',
-  compaction: 'Preserve my-mcp context during compaction.',
-});
-
-hooks.beforeToolCall({
-  match: /^Bash/,
-  handler: (ctx) => {
-    if (ctx.args.command?.includes('rm -rf')) {
-      return { block: true, reason: 'Dangerous command blocked' };
-    }
+// 2. 声明 hook（每个 agent 独立声明，内容由用户完全控制）
+// hooks/claude-code.ts
+const claudeHooks = defineHooks('claude-code', [
+  {
+    events: ['UserPromptSubmit'],
+    content: '#!/bin/bash\necho "<reminder>Use my-mcp tools.</reminder>"',
   },
+  {
+    events: ['PreToolUse'],
+    content:
+      '#!/bin/bash\n# 拦截危险操作\nTOOL_NAME="$HOOK_TOOL_NAME"\nif [[ "$TOOL_NAME" == "Bash" ]]; then echo "checked"; fi',
+  },
+]);
+
+// hooks/opencode.ts
+const opencodeHooks = defineHooks('opencode', {
+  events: ['experimental.chat.messages.transform'],
+  content: `export default {
+    name: 'my-mcp',
+    hooks: {
+      'experimental.chat.messages.transform': async (messages) => {
+        messages.push({ role: 'user', content: '<reminder>Use my-mcp tools.</reminder>' });
+        return messages;
+      },
+    },
+  };`,
 });
 
 // 3. 检测当前 agent
 const agent = await detectAgent();
 if (!agent) throw new Error('No supported agent detected');
 
-// 4. 注入 prompt 到 agent 配置文件
+// 4. 注入 prompt
 await injectPrompt(agent, '## My MCP\nInstructions for the agent...');
 
-// 5. 安装 hooks（自动翻译为 agent 原生格式）
-const result = await installHooks(agent);
+// 5. 安装 hooks
+const result = await installHooks(agent, [claudeHooks, opencodeHooks]);
 console.log(`Hooks installed: ${result.filesWritten.join(', ')}`);
-console.log(`Warnings: ${result.warnings.join('\n')}`);
 
 // 6. 获取数据目录路径
 const dataDir = getDataDir(); // global scope
-const projectDir = getDataDir({ scope: 'project', projectRoot: '/path/to/project' });
 ```
 
 ## API
@@ -83,23 +93,15 @@ createKit(name: string, options?: KitOptions): Kit
 
 返回的 Kit 对象包含以下方法：
 
-| 方法                                    | 说明                          |
-| --------------------------------------- | ----------------------------- |
-| `injectPrompt(agent, prompt, options?)` | 注入 prompt 到 agent 配置文件 |
-| `hasPromptInjected(agent, options?)`    | 检查 prompt 是否已注入        |
-| `installHooks(agent)`                   | 安装 hooks                    |
-| `uninstallHooks(agent)`                 | 卸载 hooks                    |
-| `hasHooksInstalled(agent)`              | 检查 hooks 是否已安装         |
-| `getDataDir(options?)`                  | 获取跨平台数据目录路径        |
-
-### Hook 系统
-
-Hook 系统分为两个阶段：**声明**和**安装**。
-
-1. **声明**：通过全局 `hooks.*` API 声明意图（`inject` / `beforeToolCall` / `afterToolCall` / `onSession` / `onPermission`），以及 `raw` / `extend` 两种高级注册方式
-2. **安装**：调用 `kit.installHooks(agent)` 时，从全局注册中心读取所有声明，翻译为目标 agent 的原生格式并写入磁盘
-
-详细的 API 说明、示例、三层优先级机制和降级行为，请参阅 **[Hook 使用指南](docs/hook-usage.md)**。各 agent 原生 hook 能力的完整横向对比，请参阅 **[Hook 横向对比](docs/hooks-comparison.md)**。
+| 方法                                    | 说明                                                      |
+| --------------------------------------- | --------------------------------------------------------- |
+| `injectPrompt(agent, prompt, options?)` | 注入 prompt 到 agent 配置文件                             |
+| `hasPromptInjected(agent, options?)`    | 检查 prompt 是否已注入                                    |
+| `installHooks(agent, hooks)`            | 安装 hooks（传入 defineHooks 声明）                       |
+| `uninstallHooks(agent)`                 | 卸载 hooks                                                |
+| `hasHooksInstalled(agent)`              | 检查 hooks 是否已安装                                     |
+| `getDataDir(options?)`                  | 获取跨平台数据目录路径                                    |
+| `resolvePaths(agent, options?)`         | 解析 agent 相关路径（配置文件、hook 目录、settings 文件） |
 
 ### Kit 方法详情
 
@@ -115,15 +117,20 @@ injectPrompt(agent: AgentType, prompt: string, options?: ScopeOptions): Promise<
 - 后续调用：替换已有标记块（幂等更新）
 - 自动创建目录和文件
 
-#### `kit.installHooks(agent)`
+#### `kit.installHooks(agent, hooks)`
 
-为指定 agent 安装 hooks。从 hook 注册中心读取所有声明，翻译为原生格式，写入文件。
+为指定 agent 安装 hooks。接受一个或多个 `HookSet`（由 `defineHooks()` 返回），将内容写入 agent 的 hook 目录。
 
 ```typescript
-installHooks(agent: AgentType): Promise<HookInstallResult>
+installHooks(agent: AgentType, hooks: HookSet | HookSet[]): Promise<HookInstallResult>
 ```
 
-返回值包含完整的降级信息：
+- 自动过滤：只处理与 `agent` 匹配的 `HookSet`，其余忽略
+- Claude Code / Codex：写入 shell 脚本 + 自动注册到 `settings.json`
+- OpenCode：写入 TypeScript 插件文件到 plugins 目录
+- OpenClaw：生成 `HOOK.md`（YAML frontmatter）+ `handler.ts`
+
+返回值：
 
 ```typescript
 interface HookInstallResult {
@@ -132,20 +139,11 @@ interface HookInstallResult {
   filesWritten: string[];
   settingsUpdated: boolean;
   notes: string[];
-  warnings: string[]; // 降级/冲突警告
-  skipped: SkippedIntent[]; // 被跳过的意图
+  warnings: string[];
   error?: string;
 }
 ```
 
-各 agent 的翻译方式：
-
-| Agent               | 生成内容                                                |
-| ------------------- | ------------------------------------------------------- |
-| claude-code / codex | Shell 脚本（多个原生 hook），自动注册到 `settings.json` |
-| openclaw            | `HOOK.md` + `handler.ts`（内部 hook + 插件 hook）       |
-| opencode            | 单个 TypeScript 插件文件（多个 hook 合并）              |
-
 #### `kit.uninstallHooks(agent)`
 
 清理已安装的 hook 文件和 settings.json 条目。
@@ -169,6 +167,88 @@ getDataDir(options?: ScopeOptions): string
 
 全局路径可通过环境变量覆盖（默认变量名：`{NAME}_DATA_DIR`）。
 
+#### `kit.resolvePaths(agent, options?)`
+
+解析指定 agent 的所有相关路径。自动使用 kit 的 `name` 作为 toolName，使用侧无需关心。
+
+```typescript
+resolvePaths(agent: AgentType, options?: ScopeOptions): AgentPaths
+```
+
+返回值：
+
+```typescript
+interface AgentPaths {
+  configFile: string; // agent 配置文件路径（始终返回）
+  hookDir?: string; // hook 目录路径（始终返回，因为 kit 已绑定 toolName）
+  settingsFile?: string; // settings.json 路径（仅 claude-code / codex）
+}
+```
+
+示例：
+
+```typescript
+const kit = createKit('mnemo');
+
+// Global scope
+const paths = kit.resolvePaths('claude-code');
+// → {
+//     configFile: '~/.claude/CLAUDE.md',
+//     hookDir: '~/.claude/hooks/mnemo',
+//     settingsFile: '~/.claude/settings.json',
+//   }
+
+// Project scope
+const paths = kit.resolvePaths('opencode', { scope: 'project', projectRoot: '/my/project' });
+// → {
+//     configFile: '/my/project/AGENTS.md',
+//     hookDir: '~/.config/opencode/plugins',
+//   }
+```
+
+### Hook 系统
+
+Hook 系统分为两个阶段：**声明**和**安装**。
+
+1. **声明**：通过 `defineHooks(agent, definitions)` 纯函数声明 hook 内容。每个 agent 独立声明，内容由用户完全控制。支持分文件组织。
+2. **安装**：调用 `kit.installHooks(agent, hooks)` 时，将声明内容写入目标 agent 的 hook 目录。
+
+#### `defineHooks(agent, definitions)`
+
+纯函数，不依赖任何实例或全局状态。做运行时校验（事件名合法性、content 非空），返回类型安全的 `HookSet` 数据对象。
+
+```typescript
+import { defineHooks } from '@s_s/agent-kit';
+
+// 单条声明
+const hooks = defineHooks('claude-code', {
+  events: ['PreToolUse', 'PostToolUse'], // 多事件共享同一内容
+  content: '#!/bin/bash\necho "hook fired"',
+});
+
+// 多条声明
+const hooks = defineHooks('claude-code', [
+  { events: ['PreToolUse'], content: '#!/bin/bash\necho "pre"' },
+  { events: ['PostToolUse'], content: '#!/bin/bash\necho "post"' },
+]);
+
+// OpenClaw — 支持 description 参数
+const hooks = defineHooks('openclaw', {
+  events: ['session_start', 'before_tool_call'],
+  content: 'export default async function(event) { return event; }',
+  description: '注入项目规范到每轮对话',
+});
+```
+
+**设计原则**：agent-kit 是"安装器"而非"翻译器"。用户提供各 agent 的原生 hook 内容，agent-kit 只负责：
+
+- 知道正确的文件路径
+- 写入文件
+- 管理 settings.json 合并（Claude Code / Codex）
+- 安装 / 卸载生命周期
+
+详细的使用示例和各 agent 事件名列表，请参阅 **[Hook 使用指南](docs/hook-usage.md)**。各 agent 原生 hook 能力的完整横向对比，请参阅 **[Hook 横向对比](docs/hooks-comparison.md)**。
+
 ### 独立函数
 
 以下函数不依赖 kit 实例，可直接使用。
@@ -208,23 +288,6 @@ detectProjectRoot(cwd?: string): Promise<string>
 
 优先使用 `git rev-parse --show-toplevel`，失败则向上遍历查找标记文件（`.git`、`package.json`、`pyproject.toml`、`Cargo.toml`、`go.mod`），都未找到则回退到 `cwd`。
 
-### 能力矩阵 API
-
-编程式查询各 agent 对各 intent 的支持程度。
-
-```typescript
-import { CAPABILITY_MATRIX, checkDegradation, isIntentFullyUnsupported } from '@s_s/agent-kit';
-
-// 查询特定能力
-CAPABILITY_MATRIX.opencode.beforeToolCall.block.level; // 'partial'
-
-// 检查某 intent 在某 agent 上的降级情况
-const warnings = checkDegradation('opencode', 'beforeToolCall');
-
-// 检查是否完全不支持
-isIntentFullyUnsupported('openclaw', 'onPermission'); // true
-```
-
 ## 类型
 
 ```typescript
@@ -246,10 +309,31 @@ interface Kit {
   readonly name: string;
   injectPrompt(agent: AgentType, prompt: string, options?: ScopeOptions): Promise<void>;
   hasPromptInjected(agent: AgentType, options?: ScopeOptions): Promise<boolean>;
-  installHooks(agent: AgentType): Promise<HookInstallResult>;
+  installHooks(agent: AgentType, hooks: HookSet | HookSet[]): Promise<HookInstallResult>;
   uninstallHooks(agent: AgentType): Promise<{ success: boolean; removed: string[]; error?: string }>;
   hasHooksInstalled(agent: AgentType): Promise<boolean>;
   getDataDir(options?: ScopeOptions): string;
+  resolvePaths(agent: AgentType, options?: ScopeOptions): AgentPaths;
+}
+
+// Agent 路径
+interface AgentPaths {
+  configFile: string;
+  hookDir?: string;
+  settingsFile?: string;
+}
+
+// Hook 定义
+interface HookDefinition<A extends AgentType = AgentType> {
+  events: string[]; // agent 原生事件名
+  content: string; // hook 内容（shell 脚本、TypeScript 代码等）
+  description?: string; // OpenClaw 专属 — HOOK.md 描述
+}
+
+// defineHooks() 返回的数据对象
+interface HookSet<A extends AgentType = AgentType> {
+  readonly agent: A;
+  readonly definitions: readonly HookDefinition<A>[];
 }
 
 interface HookInstallResult {
@@ -259,17 +343,8 @@ interface HookInstallResult {
   settingsUpdated: boolean;
   notes: string[];
   warnings: string[];
-  skipped: SkippedIntent[];
   error?: string;
 }
-
-interface SkippedIntent {
-  intent: string;
-  agent: string;
-  reason: string;
-}
-
-type SupportLevel = 'supported' | 'partial' | 'unsupported';
 ```
 
 ## 支持的 Agent

package/build/create-kit.js

@@ -1,6 +1,6 @@
 import { injectPrompt, hasPromptInjected } from './prompt.js';
 import { installHooks, uninstallHooks, hasHooksInstalled } from './hooks.js';
-import { getDataDir } from './platform.js';
+import { getDataDir, resolveAgentPaths } from './paths.js';
 /**
  * Create a kit instance bound to the given tool name.
  *
@@ -37,8 +37,8 @@ export function createKit(name, options) {
         hasPromptInjected(agent, scopeOptions) {
             return hasPromptInjected(name, agent, scopeOptions);
         },
-        installHooks(agent) {
-            return installHooks(name, agent);
+        installHooks(agent, hooks) {
+            return installHooks(name, agent, hooks);
         },
         uninstallHooks(agent) {
             return uninstallHooks(name, agent);
@@ -49,6 +49,9 @@ export function createKit(name, options) {
         getDataDir(scopeOptions) {
             return getDataDir(config, scopeOptions);
         },
+        resolvePaths(agent, scopeOptions) {
+            return resolveAgentPaths(agent, name, scopeOptions);
+        },
     };
 }
 //# sourceMappingURL=create-kit.js.map

package/build/create-kit.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-kit.js","sourceRoot":"","sources":["../src/create-kit.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,OAAoB;IACxD,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,MAAM,GAAsB;QAC9B,IAAI;QACJ,IAAI,EAAE,OAAO,EAAE,IAAI;QACnB,WAAW,EAAE,OAAO,EAAE,WAAW;KACpC,CAAC;IAEF,OAAO;QACH,IAAI,IAAI;YACJ,OAAO,IAAI,CAAC;QAChB,CAAC;QAED,YAAY,CAAC,KAAgB,EAAE,MAAc,EAAE,YAA2B;YACtE,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;gBAC5B,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;YAC7E,CAAC;YACD,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;QAC3D,CAAC;QAED,iBAAiB,CAAC,KAAgB,EAAE,YAA2B;YAC3D,OAAO,iBAAiB,CAAC,IAAI,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;QACxD,CAAC;QAED,YAAY,CAAC,KAAgB;YACzB,OAAO,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACrC,CAAC;QAED,cAAc,CAAC,KAAgB;YAC3B,OAAO,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACvC,CAAC;QAED,iBAAiB,CAAC,KAAgB;YAC9B,OAAO,iBAAiB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC1C,CAAC;QAED,UAAU,CAAC,YAA2B;YAClC,OAAO,UAAU,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAC5C,CAAC;KACJ,CAAC;AACN,CAAC"}
+{"version":3,"file":"create-kit.js","sourceRoot":"","sources":["../src/create-kit.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,OAAoB;IACxD,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,MAAM,GAAsB;QAC9B,IAAI;QACJ,IAAI,EAAE,OAAO,EAAE,IAAI;QACnB,WAAW,EAAE,OAAO,EAAE,WAAW;KACpC,CAAC;IAEF,OAAO;QACH,IAAI,IAAI;YACJ,OAAO,IAAI,CAAC;QAChB,CAAC;QAED,YAAY,CAAC,KAAgB,EAAE,MAAc,EAAE,YAA2B;YACtE,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;gBAC5B,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;YAC7E,CAAC;YACD,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;QAC3D,CAAC;QAED,iBAAiB,CAAC,KAAgB,EAAE,YAA2B;YAC3D,OAAO,iBAAiB,CAAC,IAAI,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;QACxD,CAAC;QAED,YAAY,CAAC,KAAgB,EAAE,KAA0B;YACrD,OAAO,YAAY,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAC5C,CAAC;QAED,cAAc,CAAC,KAAgB;YAC3B,OAAO,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACvC,CAAC;QAED,iBAAiB,CAAC,KAAgB;YAC9B,OAAO,iBAAiB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC1C,CAAC;QAED,UAAU,CAAC,YAA2B;YAClC,OAAO,UAAU,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAC5C,CAAC;QAED,YAAY,CAAC,KAAgB,EAAE,YAA2B;YACtD,OAAO,iBAAiB,CAAC,KAAK,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC;QACxD,CAAC;KACJ,CAAC;AACN,CAAC"}

package/build/define-hooks.d.ts

@@ -0,0 +1,31 @@
+import type { AgentType, HookDefinition, HookSet } from './types.js';
+/**
+ * Define hooks for a specific agent. Returns a validated HookSet that can be
+ * passed to `kit.installHooks()`.
+ *
+ * Pure function — no side effects, no global state, no instance dependency.
+ *
+ * @param agent - Target agent type.
+ * @param definitions - A single HookDefinition or an array of HookDefinitions.
+ *
+ * @example
+ * ```ts
+ * // Single definition
+ * const hooks = defineHooks('claude-code', {
+ *   events: ['PreToolUse', 'PostToolUse'],
+ *   content: '#!/bin/bash\necho "hook fired"',
+ * });
+ *
+ * // Multiple definitions
+ * const hooks = defineHooks('claude-code', [
+ *   { events: ['PreToolUse'], content: '#!/bin/bash\necho "pre"' },
+ *   { events: ['PostToolUse'], content: '#!/bin/bash\necho "post"' },
+ * ]);
+ * ```
+ */
+export declare function defineHooks<A extends AgentType>(agent: A, definitions: HookDefinition<A> | HookDefinition<A>[]): HookSet<A>;
+/**
+ * Get the set of valid event names for a given agent.
+ * Useful for tooling and documentation generation.
+ */
+export declare function getValidEvents(agent: AgentType): ReadonlySet<string>;

package/build/define-hooks.js

@@ -0,0 +1,192 @@
+import { AGENT_TYPES } from './types.js';
+// ---------------------------------------------------------------------------
+// Valid event names per agent (for runtime validation)
+// ---------------------------------------------------------------------------
+const VALID_EVENTS = {
+    'claude-code': new Set([
+        'SessionStart',
+        'InstructionsLoaded',
+        'UserPromptSubmit',
+        'PreToolUse',
+        'PermissionRequest',
+        'PostToolUse',
+        'PostToolUseFailure',
+        'Notification',
+        'SubagentStart',
+        'SubagentStop',
+        'Stop',
+        'TeammateIdle',
+        'TaskCompleted',
+        'ConfigChange',
+        'WorktreeCreate',
+        'WorktreeRemove',
+        'PreCompact',
+        'PostCompact',
+        'Elicitation',
+        'ElicitationResult',
+        'SessionEnd',
+    ]),
+    codex: new Set([
+        'SessionStart',
+        'InstructionsLoaded',
+        'UserPromptSubmit',
+        'PreToolUse',
+        'PermissionRequest',
+        'PostToolUse',
+        'PostToolUseFailure',
+        'Notification',
+        'SubagentStart',
+        'SubagentStop',
+        'Stop',
+        'TeammateIdle',
+        'TaskCompleted',
+        'ConfigChange',
+        'WorktreeCreate',
+        'WorktreeRemove',
+        'PreCompact',
+        'PostCompact',
+        'Elicitation',
+        'ElicitationResult',
+        'SessionEnd',
+    ]),
+    opencode: new Set([
+        'event',
+        'config',
+        'tool',
+        'auth',
+        'chat.message',
+        'chat.params',
+        'chat.headers',
+        'permission.ask',
+        'command.execute.before',
+        'tool.execute.before',
+        'shell.env',
+        'tool.execute.after',
+        'experimental.chat.messages.transform',
+        'experimental.chat.system.transform',
+        'experimental.session.compacting',
+        'experimental.text.complete',
+        'tool.definition',
+    ]),
+    openclaw: new Set([
+        // Plugin hooks
+        'before_model_resolve',
+        'before_prompt_build',
+        'before_agent_start',
+        'llm_input',
+        'llm_output',
+        'agent_end',
+        'before_compaction',
+        'after_compaction',
+        'before_reset',
+        'message_received',
+        'message_sending',
+        'message_sent',
+        'before_tool_call',
+        'after_tool_call',
+        'tool_result_persist',
+        'before_message_write',
+        'session_start',
+        'session_end',
+        'subagent_spawning',
+        'subagent_delivery_target',
+        'subagent_spawned',
+        'subagent_ended',
+        'gateway_start',
+        'gateway_stop',
+        // Internal hooks
+        'command:new',
+        'command:reset',
+        'command:stop',
+        'session:compact:before',
+        'session:compact:after',
+        'agent:bootstrap',
+        'gateway:startup',
+        'message:received',
+        'message:sent',
+        'message:transcribed',
+        'message:preprocessed',
+    ]),
+};
+// ---------------------------------------------------------------------------
+// defineHooks — pure validation + packaging function
+// ---------------------------------------------------------------------------
+/**
+ * Define hooks for a specific agent. Returns a validated HookSet that can be
+ * passed to `kit.installHooks()`.
+ *
+ * Pure function — no side effects, no global state, no instance dependency.
+ *
+ * @param agent - Target agent type.
+ * @param definitions - A single HookDefinition or an array of HookDefinitions.
+ *
+ * @example
+ * ```ts
+ * // Single definition
+ * const hooks = defineHooks('claude-code', {
+ *   events: ['PreToolUse', 'PostToolUse'],
+ *   content: '#!/bin/bash\necho "hook fired"',
+ * });
+ *
+ * // Multiple definitions
+ * const hooks = defineHooks('claude-code', [
+ *   { events: ['PreToolUse'], content: '#!/bin/bash\necho "pre"' },
+ *   { events: ['PostToolUse'], content: '#!/bin/bash\necho "post"' },
+ * ]);
+ * ```
+ */
+export function defineHooks(agent, definitions) {
+    // Validate agent
+    if (!AGENT_TYPES.includes(agent)) {
+        throw new Error(`defineHooks: unknown agent type "${agent}". Valid types: ${AGENT_TYPES.join(', ')}`);
+    }
+    // Normalize to array
+    const defs = Array.isArray(definitions) ? definitions : [definitions];
+    if (defs.length === 0) {
+        throw new Error('defineHooks: definitions array cannot be empty.');
+    }
+    // OpenClaw: warn if multiple definitions provided (only first is used)
+    const warnings = [];
+    if (agent === 'openclaw' && defs.length > 1) {
+        warnings.push(`defineHooks: OpenClaw only supports a single hook definition. ` +
+            `Got ${defs.length} definitions — only the first will be used.`);
+        // Log warning (user can also see it in installHooks result)
+        console.warn(warnings[0]);
+    }
+    const validEvents = VALID_EVENTS[agent];
+    for (let i = 0; i < defs.length; i++) {
+        const def = defs[i];
+        // Validate events
+        if (!Array.isArray(def.events) || def.events.length === 0) {
+            throw new Error(`defineHooks: definitions[${i}].events must be a non-empty array.`);
+        }
+        for (const event of def.events) {
+            if (!validEvents.has(event)) {
+                throw new Error(`defineHooks: unknown event "${event}" for agent "${agent}". ` +
+                    `Valid events: ${[...validEvents].join(', ')}`);
+            }
+        }
+        // Validate content
+        if (typeof def.content !== 'string' || !def.content.trim()) {
+            throw new Error(`defineHooks: definitions[${i}].content must be a non-empty string.`);
+        }
+    }
+    // For OpenClaw, only keep first definition
+    const effectiveDefs = agent === 'openclaw' && defs.length > 1 ? [defs[0]] : defs;
+    return {
+        __brand: 'HookSet',
+        agent,
+        definitions: Object.freeze([...effectiveDefs]),
+    };
+}
+/**
+ * Get the set of valid event names for a given agent.
+ * Useful for tooling and documentation generation.
+ */
+export function getValidEvents(agent) {
+    if (!AGENT_TYPES.includes(agent)) {
+        throw new Error(`getValidEvents: unknown agent type "${agent}".`);
+    }
+    return VALID_EVENTS[agent];
+}
+//# sourceMappingURL=define-hooks.js.map

package/build/define-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-hooks.js","sourceRoot":"","sources":["../src/define-hooks.ts"],"names":[],"mappings":"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"}

package/build/hooks.d.ts

@@ -1,14 +1,17 @@
-import type { AgentType, HookInstallResult } from './types.js';
+import type { AgentType, HookInstallResult, HookSet } from './types.js';
 /**
  * Install hooks for the given agent type.
  *
- * Reads all registered intents, raw hooks, and extend hooks from the hook
- * registry. Translates them into native hook files using the agent-specific
- * translator. Runs degradation checks and conflict detection.
+ * Accepts one or more HookSet (from defineHooks()). Filters to only those
+ * matching the target agent. Writes content to the agent's hook directory.
+ *
+ * For Claude Code / Codex: writes shell scripts, merges into settings.json.
+ * For OpenCode: writes TypeScript plugin files directly to plugins dir.
+ * For OpenClaw: writes HOOK.md + handler.ts, attempts CLI activation.
  *
  * @internal — called by the Kit object returned from createKit().
  */
-export declare function installHooks(name: string, agent: AgentType): Promise<HookInstallResult>;
+export declare function installHooks(name: string, agent: AgentType, hookSets: HookSet | HookSet[]): Promise<HookInstallResult>;
 /**
  * Uninstall hooks for the given agent type.
  *