Skip to contents

HookMatcher R6 Class

Source: R/hooks.R
HookMatcher.Rd

Defines when a hook callback should be triggered. Hooks can be filtered by event type and optionally by tool name pattern.

Security Note: Hook matcher configuration is read-only from the public API after construction so callbacks and matching rules cannot be swapped out accidentally at runtime.

Active bindings

event

The hook event type (see HookEvent). Read-only after construction.

pattern

Optional regex pattern for tool name filtering. Read-only after construction.

callback

The function to call when the hook fires. Read-only after construction.

timeout

Maximum execution time for the callback in seconds. Read-only after construction.

Methods

Public methods

Method new()

Create a new HookMatcher.

Usage

HookMatcher$new(event, callback, pattern = NULL, timeout = 30)

Arguments

event

The event type (must be one of HookEvent)

callback

Function to call. Signature depends on event type:

  • PreToolUse: function(tool_name, tool_input, context)

  • PostToolUse: function(tool_name, tool_result, tool_error, context)

  • Stop: function(reason, context)

  • SubagentStop: function(agent_name, task, result, context)

  • UserPromptSubmit: function(prompt, context)

  • Notification: function(message, context)

  • PreCompact: function(turns_to_compact, turns_to_keep, context)

  • SessionStart: function(context)

  • SessionEnd: function(reason, context)

pattern

Optional regex pattern to filter by tool name. Only applies to PreToolUse and PostToolUse events.

timeout

Maximum callback execution time in seconds

Returns

A new HookMatcher object

Examples

\dontrun{
# Block dangerous bash commands
HookMatcher$new(
  event = "PreToolUse",
  pattern = "^(run_bash|bash)$",
  callback = function(tool_name, tool_input, context) {
    if (grepl("rm -rf", tool_input$command)) {
      HookResultPreToolUse(permission = "deny", reason = "Dangerous!")
    } else {
      HookResultPreToolUse(permission = "allow")
    }
  }
)
}

Method matches()

Check if this hook matches a given tool name.

Usage

HookMatcher$matches(tool_name = NULL)

Arguments

tool_name

The tool name to check (can be NULL)

Returns

Logical indicating if the hook matches

Method print()

Print the hook matcher.

Usage

HookMatcher$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

HookMatcher$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples


## ------------------------------------------------
## Method `HookMatcher$new`
## ------------------------------------------------

if (FALSE) { # \dontrun{
# Block dangerous bash commands
HookMatcher$new(
  event = "PreToolUse",
  pattern = "^(run_bash|bash)$",
  callback = function(tool_name, tool_input, context) {
    if (grepl("rm -rf", tool_input$command)) {
      HookResultPreToolUse(permission = "deny", reason = "Dangerous!")
    } else {
      HookResultPreToolUse(permission = "allow")
    }
  }
)
} # }