What problem does it solve?
Pi agents need reliable hooks to observe, modify, and control their runtime behavior; pi-events provides a unified way to intercept tool calls, user input, system prompt composition, and session lifecycle events so extensions can enforce safety, mutate arguments, and inject context without modifying core agent code.
Core Features & Use Cases
- Tool Call Interception & Blocking: Pre-empt tool execution, mutate arguments in-place, or return a block reason to prevent dangerous operations.
- Result & Input Transformation: Modify tool results before finalization and transform or handle raw user input before it reaches the LLM.
- System Prompt & Context Injection: Inject persistent or transient messages and append system prompt text per turn for steering behavior.
- Session & Model Event Handling: React to session start/switch/fork, compaction events, model selection, and message streaming for state restoration and telemetry.
- Provider & Execution Inspection: Inspect or patch provider payloads and track tool execution lifecycle for logging or proxying.
- Safety Patterns: Examples and anti-patterns showing confirmations for destructive actions, lightweight streaming handlers, and proper use of command-only context methods.
Quick Start
Intercept tool calls to block destructive shell commands and inject a transient system prompt reminding the assistant to be concise.