@oh-my-pi/cli 1.3.37 → 1.3.372

package/README.md

@@ -67,18 +67,20 @@ omp installs plugins globally via npm and sets up your pi configuration:
 ├── agent/                    # Pi's agent directory
 │   ├── agents/               # Agent definitions (.md) - symlinked
 │   ├── commands/             # Slash commands (.md) - symlinked
+│   ├── hooks/omp/            # Hook loader
+│   │   └── index.ts          # Generated loader - imports hooks from node_modules
 │   ├── tools/omp/            # Tool loader
 │   │   └── index.ts          # Generated loader - imports tools from node_modules
 │   └── themes/               # Theme files (.json) - symlinked
 └── plugins/
     ├── package.json          # Installed plugins manifest
-    ├── node_modules/         # Plugin packages (tools loaded directly from here)
+    ├── node_modules/         # Plugin packages (tools/hooks loaded directly from here)
     └── store/                # Runtime configs (survives npm updates)
 ```
 
 **Non-tool files** (agents, commands, themes) are symlinked via `omp.install` entries.
 
-**Tools** are loaded directly from node_modules via a generated loader. Plugins specify `omp.tools` pointing to their tool factory. This allows tools to use npm dependencies without workarounds.
+**Tools and Hooks** are loaded directly from node_modules via generated loaders. Plugins specify `omp.tools` and/or `omp.hooks` pointing to their factory modules. This allows using npm dependencies without workarounds.
 
 ## Project-Level Overrides
 
@@ -214,16 +216,16 @@ Plugins are npm packages with an `omp` field in `package.json`:
 
 ```json
 {
-	"name": "my-cool-plugin",
-	"version": "1.0.0",
-	"keywords": ["omp-plugin"],
-	"omp": {
-		"install": [
-			{ "src": "agents/researcher.md", "dest": "agent/agents/researcher.md" },
-			{ "src": "commands/research.md", "dest": "agent/commands/research.md" }
-		]
-	},
-	"files": ["agents", "commands"]
+   "name": "my-cool-plugin",
+   "version": "1.0.0",
+   "keywords": ["omp-plugin"],
+   "omp": {
+      "install": [
+         { "src": "agents/researcher.md", "dest": "agent/agents/researcher.md" },
+         { "src": "commands/research.md", "dest": "agent/commands/research.md" }
+      ]
+   },
+   "files": ["agents", "commands"]
 }
 ```
 
@@ -233,58 +235,76 @@ For plugins with custom tools, use the `tools` field instead of `install`:
 
 ```json
 {
-	"name": "@oh-my-pi/my-tools",
-	"version": "1.0.0",
-	"keywords": ["omp-plugin"],
-	"omp": {
-		"tools": "tools"
-	},
-	"files": ["tools"],
-	"dependencies": {
-		"some-npm-package": "^1.0.0"
-	}
+   "name": "@oh-my-pi/my-tools",
+   "version": "1.0.0",
+   "keywords": ["omp-plugin"],
+   "omp": {
+      "tools": "tools"
+   },
+   "files": ["tools"],
+   "dependencies": {
+      "some-npm-package": "^1.0.0"
+   }
 }
 ```
 
 The `tools` field points to a directory containing an `index.ts` that exports a tool factory. Tools are loaded directly from node_modules, so npm dependencies work normally.
 
+### Hooks
+
+For plugins with lifecycle hooks, use the `hooks` field:
+
+```json
+{
+   "name": "@oh-my-pi/my-hooks",
+   "version": "1.0.0",
+   "keywords": ["omp-plugin"],
+   "omp": {
+      "hooks": "hooks"
+   },
+   "files": ["hooks"]
+}
+```
+
+The `hooks` field points to a directory containing an `index.ts` that exports a hook factory (`HookFactory`). Hooks subscribe to agent events like `tool_call`, `session`, etc.
+
 ### Features and Variables
 
 Plugins can define optional features and configurable variables:
 
 ```json
 {
-	"name": "@oh-my-pi/exa",
-	"version": "1.0.0",
-	"keywords": ["omp-plugin"],
-	"omp": {
-		"tools": "tools",
-		"runtime": "tools/runtime.json",
-		"variables": {
-			"apiKey": {
-				"type": "string",
-				"env": "EXA_API_KEY",
-				"description": "Exa API key",
-				"required": true
-			}
-		},
-		"features": {
-			"search": {
-				"description": "Web search capabilities",
-				"default": true
-			},
-			"websets": {
-				"description": "Curated content collections",
-				"default": false,
-				"variables": {
-					"defaultCollection": {
-						"type": "string",
-						"default": "general"
-					}
-				}
-			}
-		}
-	}
+   "name": "@oh-my-pi/exa",
+   "version": "1.0.0",
+   "keywords": ["omp-plugin"],
+   "omp": {
+      "tools": "tools",
+      "runtime": "tools/runtime.json",
+      "variables": {
+         "apiKey": {
+            "type": "string",
+            "env": "EXA_API_KEY",
+            "description": "Exa API key",
+            "required": true
+         }
+      },
+      "features": {
+         "search": {
+            "description": "Web search capabilities",
+            "default": true
+         },
+         "websets": {
+            "description": "Curated content collections",
+            "default": false,
+            "variables": {
+               "defaultCollection": {
+                  "type": "string",
+                  "default": "general"
+               }
+            }
+         }
+      }
+   }
 }
 ```