oats.hook

Hook engine for extensible event handling.

oats.hook.engine

Hook engine — executes user-defined commands at lifecycle events.

Hooks are configured in coder.json:

{
  "hooks": [
    {
      "event": "pre_tool_use",
      "matcher": "bash",
      "command": "/path/to/script.sh",
      "timeout": 30
    }
  ]
}

Hook commands receive a JSON context on stdin and must return JSON on stdout:

{
  "action": "continue",
  "modified_args": {},
  "message": "..."
}

class oats.hook.engine.HookEvent(*values)

Bases: str, Enum

Lifecycle events that can trigger hooks.

PRE_TOOL_USE = 'pre_tool_use'

POST_TOOL_USE = 'post_tool_use'

USER_PROMPT_SUBMIT = 'user_prompt_submit'

SESSION_START = 'session_start'

FILE_CHANGED = 'file_changed'

ASSISTANT_RESPONSE = 'assistant_response'

class oats.hook.engine.HookContext(session_id, event, tool_name=None, tool_args=None, tool_result_output=None, tool_result_error=None, user_prompt=None, assistant_response=None, root_session_id=None, file_path=None, working_dir=None)

Bases: object

Context passed to hook commands.

session_id: str

event: HookEvent

tool_name: str | None = None

tool_args: dict[str, Any] | None = None

tool_result_output: str | None = None

tool_result_error: str | None = None

user_prompt: str | None = None

assistant_response: str | None = None

root_session_id: str | None = None

file_path: str | None = None

working_dir: str | None = None

to_dict()

Serialize the hook context to a plain dict for JSON encoding.

Return type:

dict[str, Any]

__init__(session_id, event, tool_name=None, tool_args=None, tool_result_output=None, tool_result_error=None, user_prompt=None, assistant_response=None, root_session_id=None, file_path=None, working_dir=None)

class oats.hook.engine.HookResult(action='continue', modified_args=None, message=None)

Bases: object

Result returned by a hook command.

action: str = 'continue'

modified_args: dict[str, Any] | None = None

message: str | None = None

classmethod from_dict(data)

Deserialize a HookResult from a JSON dict.

Return type:

HookResult

classmethod continue_result()

Return a HookResult that signals the agent to continue.

Return type:

HookResult

classmethod block_result(message='')

Return a HookResult that signals the agent to stop.

Return type:

HookResult

__init__(action='continue', modified_args=None, message=None)

class oats.hook.engine.HookEngine(hooks=None)

Bases: object

Executes hook commands at lifecycle events.

Hooks are loaded from configuration and matched against events and optional tool name patterns.

__init__(hooks=None)

async fire(event, context)

Fire all hooks matching this event.

Returns the first blocking result, or continue if all pass. For pre_tool_use with “modify” action, returns modified args.

Return type:

HookResult