Listen to a session's events — gptr

Registers a session-scoped hook (rank 0) for one cataloged event (such as message_end, tool_call, turn_end) or a plugin channel containing :. The handler is function(event, ctx) and returns what the event allows. Forks never copy listeners.

Usage

gptr_on(s, event, handler, matcher = NULL)

Arguments

s: A session.
event: An event name; Claude and Codex hook names are refused with the gptr name.
handler: function(event, ctx).
matcher: NULL, a tool-name glob for tool events, or function(event) returning a flag.

Value

A function of no arguments that removes the hook, invisibly.

Examples

session = peter("hi", model = gptr_fake_provider(list("hello")), .run = FALSE)
seen = new.env()
seen$roles = character()
off = gptr_on(session, "message_end", function(event, ctx) {
  seen$roles = c(seen$roles, event$message$role)
  NULL
})
gptr_step(session)
#> gptr: thinking
#> gptr: done · 1 turn · 1.6k tokens · $0.0000
off()
seen$roles
#> [1] "user"      "assistant"