# 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.