SuperPi.Plugins.Hooks (super_pi v0.1.0)

Copy Markdown View Source

Lifecycle Hooks Plugin (SuperPi.Extension behaviour).

Implements lifecycle hook interception for workspace sessions:

  • Discovers and merges hooks.json files across workspace .agents/hooks.json and global config directories, respecting "enabled": false.
  • SessionStart (before_agent_start/2): Runs startup hooks once and injects systemMessage steps.
  • PreInvocation (before_request/2): Runs before model invocation and injects transient ephemeralMessage or userMessage steps into derived.messages for that turn.
  • PreToolUse (before_tool/3): Matches tool names against matcher ("*", "", or regex), sends camelCase JSON payload on stdin, and parses stdout JSON (decision: "allow" | "deny" | "ask" | "force_ask" and shallow top-level overwrite map).
  • PostToolUse (after_tool/4): Runs matching post-tool commands with error metadata when a tool fails.
  • PostInvocation (after_tools/2): Supports terminationBehavior: "force_continue".
  • Stop (after_run/2): Sends terminationReason: "NO_TOOL_CALL" and honors decision: "continue" + reason.

Summary

Functions

description()

id()

matcher_matches?(pattern, tool_name)

name()

run_hook_command(handler, stdin_map, working_dir)