goclaw/internal/hooks/builtin

Builtin Hooks

Canonical, embed-shipped hook rows. Users may toggle enabled but cannot edit content — the embedded .js is overwritten on every boot.

Adding a new builtin

1. Pick a stable kebab identifier (pii-redactor, sql-guard). Never rename: the DB primary key is UUIDv5(namespace, id + "/" + event) and renaming would orphan any existing rows.

2. Drop my-feature.js alongside builtins.yaml. The script sees the goja sandboxed globals event and result, plus the usual JSON.*, Math.*. No network, no I/O, no timers.

3. Add an entry to builtins.yaml:

   - id: my-feature
     version: 1
     events: [pre_tool_use]
     scope: global
     timeout_ms: 200
     on_timeout: allow
     priority: 500
     mutable_fields: [toolInput.command]
     source_file: my-feature.js
     description: "One-line user-facing summary."
   

4. Bump version whenever the JS content changes. On next boot, matching rows get UPDATEd in-place (the user's enabled toggle is preserved).

5. Remove _placeholder.js once this is the first real .js in the package.

Operator escape hatch

Operators can force-disable any builtin by id via hooks.builtin_disable in config.json — useful when a builtin misbehaves before the next release:

{
  "hooks": {
    "builtin_disable": ["pii-redactor"]
  }
}

The row stays in the DB (history preserved); only enabled=false is applied.

Version reconciliation rules

Embed version	DB version	Outcome
missing row	—	INSERT, enabled=true
newer	older	UPDATE content; keep user's enabled toggle
equal	equal	no-op
older	newer	WARN log; keep DB (no rollback)

A downgrade happens when someone rolls back the binary but the DB has already been written by a newer version. We never destructively rewrite; operators must resolve manually.