Skip to content

The open-source app everyone uses to manage agents at work

docs: survey pi and pi-mono hook surfaces

dotta87db949d3f01
diff --git a/doc/plans/2026-04-07-pi-hooks-survey.md b/doc/plans/2026-04-07-pi-hooks-survey.md
new file mode 100644
index 0000000000..bc67a70453
--- /dev/null
+++ b/doc/plans/2026-04-07-pi-hooks-survey.md
@@ -0,0 +1,248 @@
+# Pi Hook Survey
+
+Status: investigation note
+Date: 2026-04-07
+
+## Why this exists
+
+We were asked to find the hook surfaces exposed by `pi` and `pi-mono`, then decide which ideas transfer cleanly into Paperclip.
+
+This note is based on direct source inspection of:
+
+- `badlogic/pi` default branch and `pi2` branch
+- `badlogic/pi-mono` `packages/coding-agent`
+- current Paperclip plugin and adapter surfaces in this repo
+
+## Short answer
+
+- Current `pi` does not expose a comparable extension hook API. What it exposes today is a JSON event stream from `pi-agent`.
+- `pi-mono` does expose a real extension hook system. It is broad, typed, and intentionally allows mutation of agent/runtime behavior.
+- Paperclip should copy only the safe subset:
+ - typed event subscriptions
+ - read-only run lifecycle events
+ - explicit worker lifecycle hooks
+ - plugin-to-plugin events
+- Paperclip should not copy the dangerous subset:
+ - arbitrary mutation hooks on core control-plane decisions
+ - project-local plugin loading
+ - built-in tool shadowing by name collision
+
+## What `pi` has today
+
+Current `badlogic/pi` is primarily a GPU pod manager plus a lightweight agent runner. It does not expose a `pi.on(...)`-style extension API like `pi-mono`.
+
+The closest thing to hooks is the `pi-agent --json` event stream:
+
+- `session_start`
+- `user_message`
+- `assistant_start`
+- `assistant_message`
+- `thinking`
+- `tool_call`
+- `tool_result`
+- `token_usage`
+- `error`
+- `interrupted`
+
+That makes `pi` useful as an event producer, but not as a host for third-party runtime interception.
+
+## What `pi-mono` has
+
+`pi-mono` exposes a real extension API through `packages/coding-agent/src/core/extensions/types.ts`.
+
+### Extension event hooks
+
+Verified `pi.on(...)` hook names:
+
+- `resources_discover`
+- `session_start`
+- `session_before_switch`
+- `session_before_fork`
+- `session_before_compact`
+- `session_compact`
+- `session_shutdown`
+- `session_before_tree`
+- `session_tree`
+- `context`
+- `before_provider_request`
+- `before_agent_start`
+- `agent_start`
+- `agent_end`
+- `turn_start`
+- `turn_end`
+- `message_start`
+- `message_update`
+- `message_end`
+- `tool_execution_start`
+- `tool_execution_update`
+- `tool_execution_end`
+- `model_select`
+- `tool_call`
+- `tool_result`
+- `user_bash`
+- `input`
+
+### Other extension surfaces
+
+`pi-mono` extensions can also:
+
+- `registerTool(...)`
+- `registerCommand(...)`
+- `registerShortcut(...)`
+- `registerFlag(...)`
+- `registerMessageRenderer(...)`
+- `registerProvider(...)`
+- `unregisterProvider(...)`
+- use an inter-extension event bus via `pi.events`
+
+### Important behavior
+
+`pi-mono` hooks are not just observers. Several can actively mutate behavior:
+
+- `before_agent_start` can rewrite the effective system prompt and inject messages
+- `context` can replace the message set before an LLM call
+- `before_provider_request` can rewrite the serialized provider payload
+- `tool_call` can mutate tool inputs and block execution
+- `tool_result` can rewrite tool output
+- `user_bash` can replace shell execution entirely
+- `input` can transform or fully handle user input before normal processing
+
+That is a good fit for a local coding harness. It is not automatically a good fit for a company control plane.
+
+## What Paperclip already has
+
+Paperclip already has several hook-like surfaces, but they are much narrower and safer:
+
+- plugin worker lifecycle hooks such as `setup()` and `onHealth()`
+- declared webhook endpoints for plugins
+- scheduled jobs
+- a typed plugin event bus with filtering and plugin namespacing
+- adapter runtime hooks for logs/status/usage in the run pipeline
+
+The plugin event bus is already pointed in the right direction:
+
+- core domain events can be subscribed to
+- filters are applied server-side
+- plugin-emitted events are namespaced under `plugin.<pluginId>.*`
+- plugins do not override core behavior by name collision
+
+## What transfers well to Paperclip
+
+These ideas from `pi-mono` fit Paperclip with little conceptual risk:
+
+### 1. Read-only run lifecycle subscriptions
+
+Paperclip should continue exposing run and transcript events to plugins, for example:
+
+- run started / finished
+- tool started / finished
+- usage reported
+- issue comment created
+
+This matches Paperclip's control-plane posture: observe, react, automate.
+
+### 2. Plugin-to-plugin events
+
+Paperclip already has this. It is worth keeping and extending.
+
+This is the clean replacement for many ad hoc hook chains.
+
+### 3. Explicit worker lifecycle hooks
+
+Paperclip already has `setup()` and `onHealth()`. That is the right shape.
+
+If more lifecycle is needed, it should stay explicit and host-controlled.
+
+### 4. Trusted adapter-level prompt/runtime middleware
+
+Some `pi-mono` ideas do belong in Paperclip, but only inside trusted adapter/runtime code:
+
+- prompt shaping before a run starts
+- provider request customization
+- tool execution wrappers for local coding adapters
+
+This should be an adapter surface, not a general company plugin surface.
+
+## What should not transfer directly
+
+These `pi-mono` capabilities are a bad fit for Paperclip core:
+
+### 1. Arbitrary mutation hooks on control-plane decisions
+
+Paperclip should not let general plugins rewrite:
+
+- issue checkout semantics
+- approval outcomes
+- budget enforcement
+- assignment rules
+- company scoping
+
+Those are core invariants.
+
+### 2. Tool shadowing by name collision
+
+`pi-mono`'s low-friction override model is great for a personal coding harness.
+
+Paperclip should keep plugin tools namespaced and non-shadowing.
+
+### 3. Project-local plugin loading
+
+Paperclip is an operator-controlled control plane. Repo-local plugin auto-loading would make behavior too implicit and too hard to govern.
+
+### 4. UI-session-specific hooks as first-class product surface
+
+Hooks like:
+
+- `session_before_switch`
+- `session_before_fork`
+- `session_before_tree`
+- `model_select`
+- `input`
+- `user_bash`
+
+are tied to `pi-mono` being an interactive terminal coding harness.
+
+They do not map directly to Paperclip's board-and-issues model.
+
+## Recommended Paperclip direction
+
+If we want a "hooks" story inspired by `pi-mono`, it should split into two layers:
+
+### Layer 1: safe control-plane plugins
+
+Allowed surfaces:
+
+- typed domain event subscriptions
+- jobs
+- webhooks
+- plugin-to-plugin events
+- UI slots and bridge actions
+- plugin-owned tools and data endpoints
+
+Disallowed:
+
+- mutation of core issue/approval/budget invariants
+
+### Layer 2: trusted runtime middleware
+
+For adapters and other trusted runtime packages only:
+
+- prompt assembly hooks
+- provider payload hooks
+- tool execution wrappers
+- transcript rendering helpers
+
+This is where the best `pi-mono` runtime ideas belong.
+
+## Bottom line
+
+If the question is "what hooks do `pi` and `pi-mono` have?":
+
+- `pi`: JSON output events, not a general extension hook system
+- `pi-mono`: a broad extension hook API with 27 named event hooks plus tool/command/provider registration
+
+If the question is "what works for Paperclip too?":
+
+- yes: typed event subscriptions, worker lifecycle hooks, namespaced plugin events, read-only run lifecycle events
+- maybe, but trusted-only: prompt/provider/tool middleware around adapter execution
+- no: arbitrary mutation hooks on control-plane invariants, project-local plugin loading, tool shadowing