zhi
5a8f490cc2
Plugin development reference and workflows based on real development experience (Dirigent, ContractorAgent, PrismFacet). Docs: structure, entry-point, hooks, tools, state, config, debugging Workflows: create-plugin, add-hook Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
41 lines
1.1 KiB
Markdown
41 lines
1.1 KiB
Markdown
# Add Hook
|
|
|
|
When adding a new hook handler to an existing plugin.
|
|
|
|
> See `{baseDir}/docs/hooks.md` for available hooks and dedup patterns.
|
|
|
|
## Process
|
|
|
|
### 1. Create Hook File
|
|
|
|
Add `plugin/hooks/<hook-name>.ts`. Export a registration function:
|
|
|
|
```typescript
|
|
export function registerMyHook(api, config) {
|
|
// Set up dedup on globalThis
|
|
// api.on("<hook-name>", handler)
|
|
}
|
|
```
|
|
|
|
### 2. Add Dedup
|
|
|
|
Choose the right dedup pattern:
|
|
- `before_model_resolve`, `before_prompt_build` → WeakSet on event object
|
|
- `agent_end` → Set on runId with size cap (500)
|
|
- `gateway_start/stop` → globalThis flag (in index.ts, not in hook file)
|
|
|
|
### 3. Register in index.ts
|
|
|
|
Import and call the registration function in the `register()` method.
|
|
|
|
Hooks that need to run every register() call (agent-scoped): put outside the lifecycle guard.
|
|
Hooks that should run once (gateway-scoped): put inside the lifecycle guard.
|
|
|
|
### 4. If Prompt Injection
|
|
|
|
If the hook returns `prependSystemContext` or `appendSystemContext`, ensure `allowPromptInjection: true` is set in the plugin's config entry and in the install script.
|
|
|
|
### 5. Test
|
|
|
|
Reinstall, restart gateway, verify via logs.
|