Define an event hook

A hook runs handler(event, ctx) for one event of the catalog (see gptr_api()$features) or for a plugin channel named "<plugin>:<topic>". What the handler may return depends on the event: patches for tool_result, a decision for tool_call, nothing for notifications. Handlers of tool_call, permission_request and document_write fail closed: an error blocks or denies, and a tool_call answer with an unknown decision (anything but "block", "modify" with an input list, or "allow"; for example "deny") blocks.

Usage

gptr_hook(event, handler, matcher = NULL)

Arguments

event

Event name.

handler

function(event, ctx).

matcher

NULL, a tool-name glob such as "mcp__*", or function(event) returning TRUE for events the handler wants.

Value

A spec of class c("gptr_hook", "gptr_spec"), named after its event.

Examples

gptr_hook("tool_result", function(event, ctx) NULL, matcher = "r")
#> <gptr_hook tool_result>
#>   event: tool_result
#>   handler: <fn>
#>   matcher: r
#>   api_version: 1.0