mirror of
https://github.com/tiennm99/goclaw.git
synced 2026-08-07 00:23:46 +00:00
viettranx
95bdb23a36
- docs/agent-hooks.md: handler reference, lifecycle events, security model - examples/hooks/: 5 runnable JSON configs (audit, lint, block-rm-rf, Discord notify, context injector) - docs/17-changelog.md: Wave 0 entry - Makefile: hooks-specific test targets - CLAUDE.md: cross-reference
46 lines
2.4 KiB
Markdown
46 lines
2.4 KiB
Markdown
# Example Hooks Library
|
|
|
|
Copy-paste-ready hook configurations for common use cases. Each JSON is a valid `hooks.create` WS payload — send it via the Web UI → **Hooks → Create** (paste into the relevant fields) or POST directly to the RPC endpoint.
|
|
|
|
## Safety reminders
|
|
|
|
- **Review regex matchers** before enabling. A too-broad matcher on a prompt hook drains token budget. Prefer anchored patterns like `^(exec|shell)$`.
|
|
- **`command` hooks require Lite edition.** On Standard the UI greys them out and dispatch fails closed.
|
|
- **SSRF-safe HTTP hooks**: URLs are resolved + pinned before the request. Loopback/private ranges are blocked in production.
|
|
- **Authorization headers** get AES-256-GCM encrypted at rest. Never commit plaintext secrets to these JSON files.
|
|
- **Test in staging first.** Use the `Test` tab in the UI — it runs with `dryRun=true` and does NOT write to `hook_executions`.
|
|
|
|
## Catalog
|
|
|
|
| File | Event | Handler | Scope | Purpose |
|
|
|---|---|---|---|---|
|
|
| `block-rm-rf.json` | `pre_tool_use` | command | agent | Block dangerous `rm -rf /` via local shell script. Lite only. |
|
|
| `auto-lint-after-write.json` | `post_tool_use` | http | agent | Fire-and-forget lint request after file writes. |
|
|
| `audit-tool-usage.json` | `post_tool_use` | http | tenant | Stream every tool invocation to an external audit sink. |
|
|
| `session-context-injector.json` | `session_start` | http | agent | Injects project metadata into the agent context at start. |
|
|
| `notify-discord-on-stop.json` | `stop` | http | tenant | Discord webhook notification when a session ends. |
|
|
|
|
## Usage
|
|
|
|
### Via Web UI
|
|
|
|
1. Open `/hooks` → click **Create hook**.
|
|
2. Copy fields from the example JSON into the form.
|
|
3. For `http.config.headers`, paste your secret in the Authorization field — the server encrypts it before storing.
|
|
4. Click **Save**, then **Test** with a sample event before enabling in production.
|
|
|
|
### Via WS RPC
|
|
|
|
```bash
|
|
wscat -c ws://localhost:18790/ws
|
|
# After connect:
|
|
> {"id":"1","method":"hooks.create","params": <paste JSON here> }
|
|
```
|
|
|
|
## Conventions
|
|
|
|
- `tenant_id` omitted → current tenant from WS session. Set `scope: "global"` to apply cross-tenant (master required).
|
|
- `agent_id` required for `scope: "agent"`; otherwise leave null.
|
|
- `priority: 10` is the recommended default. Higher priority hooks run first; first `block` wins the chain.
|
|
- `on_timeout: "block"` for anything security-sensitive; `"allow"` for observation-only.
|