# `SuperPi.Plugins.Hooks`
[🔗](https://github.com/oleksandr/super-pi-beam/blob/v0.1.0/lib/super_pi/plugins/hooks.ex#L1)

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`.

# `description`

# `id`

# `matcher_matches?`

# `name`

# `run_hook_command`

---

*Consult [api-reference.md](api-reference.md) for complete listing*