@mariozechner/pi-coding-agent 0.34.2 → 0.36.0

package/docs/rpc.md

@@ -52,9 +52,9 @@ With images:
 
 If the agent is streaming and no `streamingBehavior` is specified, the command returns an error.
 
-**Hook commands**: If the message is a hook command (e.g., `/mycommand`), it executes immediately even during streaming. Hook commands manage their own LLM interaction via `pi.sendMessage()`.
+**Extension commands**: If the message is a hook command (e.g., `/mycommand`), it executes immediately even during streaming. Extension commands manage their own LLM interaction via `pi.sendMessage()`.
 
-**Slash commands**: File-based slash commands (from `.md` files) are expanded before sending/queueing.
+**Prompt templates**: File-based prompt templates (from `.md` files) are expanded before sending/queueing.
 
 Response:
 ```json
@@ -65,7 +65,7 @@ The `images` field is optional. Each image uses `ImageContent` format with base6
 
 #### steer
 
-Queue a steering message to interrupt the agent mid-run. Delivered after current tool execution, remaining tools are skipped. File-based slash commands are expanded. Hook commands are not allowed (use `prompt` instead).
+Queue a steering message to interrupt the agent mid-run. Delivered after current tool execution, remaining tools are skipped. File-based prompt templates are expanded. Extension commands are not allowed (use `prompt` instead).
 
 ```json
 {"type": "steer", "message": "Stop and do this instead"}
@@ -80,7 +80,7 @@ See [set_steering_mode](#set_steering_mode) for controlling how steering message
 
 #### follow_up
 
-Queue a follow-up message to be processed after the agent finishes. Delivered only when agent has no more tool calls or steering messages. File-based slash commands are expanded. Hook commands are not allowed (use `prompt` instead).
+Queue a follow-up message to be processed after the agent finishes. Delivered only when agent has no more tool calls or steering messages. File-based prompt templates are expanded. Extension commands are not allowed (use `prompt` instead).
 
 ```json
 {"type": "follow_up", "message": "After you're done, also do this"}

package/docs/sdk.md

@@ -129,7 +129,7 @@ interface AgentSession {
 
 ### Prompting and Message Queueing
 
-The `prompt()` method handles slash commands, hook commands, and message sending:
+The `prompt()` method handles prompt templates, extension commands, and message sending:
 
 ```typescript
 // Basic prompt (when not streaming)
@@ -146,8 +146,8 @@ await session.prompt("After you're done, also check X", { streamingBehavior: "fo
 ```
 
 **Behavior:**
-- **Hook commands** (e.g., `/mycommand`): Execute immediately, even during streaming. They manage their own LLM interaction via `pi.sendMessage()`.
-- **File-based slash commands** (from `.md` files): Expanded to their content before sending/queueing.
+- **Extension commands** (e.g., `/mycommand`): Execute immediately, even during streaming. They manage their own LLM interaction via `pi.sendMessage()`.
+- **File-based prompt templates** (from `.md` files): Expanded to their content before sending/queueing.
 - **During streaming without `streamingBehavior`**: Throws an error. Use `steer()` or `followUp()` directly, or specify the option.
 
 For explicit queueing during streaming:
@@ -160,7 +160,7 @@ await session.steer("New instruction");
 await session.followUp("After you're done, also do this");
 ```
 
-Both `steer()` and `followUp()` expand file-based slash commands but error on hook commands (hook commands cannot be queued).
+Both `steer()` and `followUp()` expand file-based prompt templates but error on extension commands (extension commands cannot be queued).
 
 ### Agent and AgentState
 
@@ -260,18 +260,16 @@ const { session } = await createAgentSession({
 ```
 
 `cwd` is used for:
-- Project hooks (`.pi/hooks/`)
-- Project tools (`.pi/tools/`)
+- Project extensions (`.pi/extensions/`)
 - Project skills (`.pi/skills/`)
-- Project commands (`.pi/commands/`)
+- Project prompts (`.pi/prompts/`)
 - Context files (`AGENTS.md` walking up from cwd)
 - Session directory naming
 
 `agentDir` is used for:
-- Global hooks (`hooks/`)
-- Global tools (`tools/`)
+- Global extensions (`extensions/`)
 - Global skills (`skills/`)
-- Global commands (`commands/`)
+- Global prompts (`prompts/`)
 - Global context file (`AGENTS.md`)
 - Settings (`settings.json`)
 - Custom models (`models.json`)
@@ -442,113 +440,79 @@ const { session } = await createAgentSession({
 
 ```typescript
 import { Type } from "@sinclair/typebox";
-import { createAgentSession, discoverCustomTools, type CustomTool } from "@mariozechner/pi-coding-agent";
+import { createAgentSession, type ToolDefinition } from "@mariozechner/pi-coding-agent";
 
 // Inline custom tool
-const myTool: CustomTool = {
+const myTool: ToolDefinition = {
   name: "my_tool",
   label: "My Tool",
   description: "Does something useful",
   parameters: Type.Object({
     input: Type.String({ description: "Input value" }),
   }),
-  execute: async (toolCallId, params) => ({
+  execute: async (toolCallId, params, onUpdate, ctx, signal) => ({
     content: [{ type: "text", text: `Result: ${params.input}` }],
     details: {},
   }),
 };
 
-// Replace discovery with inline tools
+// Pass custom tools directly
 const { session } = await createAgentSession({
-  customTools: [{ tool: myTool }],
-});
-
-// Merge with discovered tools
-const discovered = await discoverCustomTools();
-const { session } = await createAgentSession({
-  customTools: [...discovered, { tool: myTool }],
-});
-
-// Add paths without replacing discovery
-const { session } = await createAgentSession({
-  additionalCustomToolPaths: ["/extra/tools"],
+  customTools: [myTool],
 });
 ```
 
+Custom tools passed via `customTools` are combined with extension-registered tools. Extensions discovered from `~/.pi/agent/extensions/` and `.pi/extensions/` can also register tools via `pi.registerTool()`.
+
 > See [examples/sdk/05-tools.ts](../examples/sdk/05-tools.ts)
 
-### Hooks
+### Extensions
+
+Extensions are discovered from `~/.pi/agent/extensions/` and `.pi/extensions/`. You can also pass inline extensions or additional paths:
 
 ```typescript
-import { createAgentSession, discoverHooks, type HookFactory } from "@mariozechner/pi-coding-agent";
+import { createAgentSession, type ExtensionFactory } from "@mariozechner/pi-coding-agent";
 
-// Inline hook
-const loggingHook: HookFactory = (api) => {
-  // Log tool calls
-  api.on("tool_call", async (event) => {
+// Inline extension
+const myExtension: ExtensionFactory = (pi) => {
+  pi.on("tool_call", async (event, ctx) => {
     console.log(`Tool: ${event.toolName}`);
-    return undefined; // Don't block
   });
-  
-  // Block dangerous commands
-  api.on("tool_call", async (event) => {
-    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
-      return { block: true, reason: "Dangerous command" };
-    }
-    return undefined;
-  });
-  
-  // Register custom slash command
-  api.registerCommand("stats", {
-    description: "Show session stats",
-    handler: async (ctx) => {
-      const entries = ctx.sessionManager.getEntries();
-      ctx.ui.notify(`${entries.length} entries`, "info");
+
+  pi.registerCommand("hello", {
+    description: "Say hello",
+    handler: async (args, ctx) => {
+      ctx.ui.notify("Hello!", "info");
     },
   });
-  
-  // Inject messages
-  api.sendMessage({
-    customType: "my-hook",
-    content: "Hook initialized",
-    display: false,  // Hidden from TUI
-  }, false);  // Don't trigger agent turn
-  
-  // Persist hook state
-  api.appendEntry("my-hook", { initialized: true });
 };
 
-// Replace discovery
+// Pass inline extensions (merged with discovery)
 const { session } = await createAgentSession({
-  hooks: [{ factory: loggingHook }],
+  extensions: [myExtension],
 });
 
-// Disable all hooks
+// Or add paths to load (merged with discovery)
 const { session } = await createAgentSession({
-  hooks: [],
+  additionalExtensionPaths: ["/path/to/my-extension.ts"],
 });
+```
 
-// Merge with discovered
-const discovered = await discoverHooks();
-const { session } = await createAgentSession({
-  hooks: [...discovered, { factory: loggingHook }],
-});
+Extensions can register tools, subscribe to events, add commands, and more. See [extensions.md](extensions.md) for the full API.
 
-// Add paths without replacing
-const { session } = await createAgentSession({
-  additionalHookPaths: ["/extra/hooks"],
-});
-```
+**Event Bus:** Extensions can communicate via `pi.events`. Pass a shared `eventBus` to `createAgentSession()` if you need to emit/listen from outside:
 
-Hook API methods:
-- `api.on(event, handler)` - Subscribe to events
-- `api.sendMessage(message, triggerTurn?)` - Inject message (creates `CustomMessageEntry`)
-- `api.appendEntry(customType, data?)` - Persist hook state (not in LLM context)
-- `api.registerCommand(name, options)` - Register custom slash command
-- `api.registerMessageRenderer(customType, renderer)` - Custom TUI rendering
-- `api.exec(command, args, options?)` - Execute shell commands
+```typescript
+import { createAgentSession, createEventBus } from "@mariozechner/pi-coding-agent";
 
-> See [examples/sdk/06-hooks.ts](../examples/sdk/06-hooks.ts) and [docs/hooks.md](hooks.md)
+const eventBus = createEventBus();
+const { session } = await createAgentSession({ eventBus });
+
+// Listen for events from extensions
+eventBus.on("my-extension:status", (data) => console.log(data));
+```
+
+> See [examples/sdk/06-extensions.ts](../examples/sdk/06-extensions.ts) and [docs/extensions.md](extensions.md)
 
 ### Skills
 
@@ -616,11 +580,11 @@ const { session } = await createAgentSession({
 ### Slash Commands
 
 ```typescript
-import { createAgentSession, discoverSlashCommands, type FileSlashCommand } from "@mariozechner/pi-coding-agent";
+import { createAgentSession, discoverPromptTemplates, type PromptTemplate } from "@mariozechner/pi-coding-agent";
 
-const discovered = discoverSlashCommands();
+const discovered = discoverPromptTemplates();
 
-const customCommand: FileSlashCommand = {
+const customCommand: PromptTemplate = {
   name: "deploy",
   description: "Deploy the application",
   source: "(custom)",
@@ -628,11 +592,11 @@ const customCommand: FileSlashCommand = {
 };
 
 const { session } = await createAgentSession({
-  slashCommands: [...discovered, customCommand],
+  promptTemplates: [...discovered, customCommand],
 });
 ```
 
-> See [examples/sdk/08-slash-commands.ts](../examples/sdk/08-slash-commands.ts)
+> See [examples/sdk/08-prompt-templates.ts](../examples/sdk/08-prompt-templates.ts)
 
 ### Session Management
 
@@ -761,7 +725,7 @@ import {
   discoverHooks,
   discoverCustomTools,
   discoverContextFiles,
-  discoverSlashCommands,
+  discoverPromptTemplates,
   loadSettings,
   buildSystemPrompt,
 } from "@mariozechner/pi-coding-agent";
@@ -778,16 +742,18 @@ const builtIn = getModel("anthropic", "claude-opus-4-5"); // Built-in only
 const skills = discoverSkills(cwd, agentDir, skillsSettings);
 
 // Hooks (async - loads TypeScript)
-const hooks = await discoverHooks(cwd, agentDir);
+// Pass eventBus to share pi.events across hooks/tools
+const eventBus = createEventBus();
+const hooks = await discoverHooks(eventBus, cwd, agentDir);
 
 // Custom tools (async - loads TypeScript)
-const tools = await discoverCustomTools(cwd, agentDir);
+const tools = await discoverCustomTools(eventBus, cwd, agentDir);
 
 // Context files
 const contextFiles = discoverContextFiles(cwd, agentDir);
 
-// Slash commands
-const commands = discoverSlashCommands(cwd, agentDir);
+// Prompt templates
+const commands = discoverPromptTemplates(cwd, agentDir);
 
 // Settings (global + project merged)
 const settings = loadSettings(cwd, agentDir);
@@ -894,7 +860,7 @@ const { session } = await createAgentSession({
   hooks: [{ factory: auditHook }],
   skills: [],
   contextFiles: [],
-  slashCommands: [],
+  promptTemplates: [],
   
   sessionManager: SessionManager.inMemory(),
   settingsManager,
@@ -949,7 +915,10 @@ discoverSkills
 discoverHooks
 discoverCustomTools
 discoverContextFiles
-discoverSlashCommands
+discoverPromptTemplates
+
+// Event Bus (for shared hook/tool communication)
+createEventBus
 
 // Helpers
 loadSettings
@@ -977,7 +946,7 @@ type CreateAgentSessionResult
 type CustomTool
 type HookFactory
 type Skill
-type FileSlashCommand
+type PromptTemplate
 type Settings
 type SkillsSettings
 type Tool

package/docs/session.md

@@ -16,14 +16,15 @@ Sessions have a version field in the header:
 
 - **Version 1**: Linear entry sequence (legacy, auto-migrated on load)
 - **Version 2**: Tree structure with `id`/`parentId` linking
+- **Version 3**: Renamed `hookMessage` role to `custom` (extensions unification)
 
-Existing v1 sessions are automatically migrated to v2 when loaded.
+Existing sessions are automatically migrated to the current version (v3) when loaded.
 
 ## Type Definitions
 
 - [`src/core/session-manager.ts`](../src/core/session-manager.ts) - Session entry types
-- [`packages/agent/src/types.ts`](../../agent/src/types.ts) - `AgentMessage`, `Attachment`, `ThinkingLevel`
-- [`packages/ai/src/types.ts`](../../ai/src/types.ts) - `UserMessage`, `AssistantMessage`, `ToolResultMessage`, `Usage`, `ToolCall`
+- [`packages/agent-core/src/types.ts`](../../agent-core/src/types.ts) - `AgentMessage`
+- [`packages/ai/src/types.ts`](../../ai/src/types.ts) - `UserMessage`, `AssistantMessage`, `ToolResultMessage`, `Usage`, `ToolCall`, `ImageContent`, `TextContent`
 
 ## Entry Base
 
@@ -45,13 +46,13 @@ interface SessionEntryBase {
 First line of the file. Metadata only, not part of the tree (no `id`/`parentId`).
 
 ```json
-{"type":"session","version":2,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project"}
+{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project"}
 ```
 
 For sessions with a parent (created via `/branch` or `newSession({ parentSession })`):
 
 ```json
-{"type":"session","version":2,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project","parentSession":"/path/to/original/session.jsonl"}
+{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project","parentSession":"/path/to/original/session.jsonl"}
 ```
 
 ### SessionMessageEntry
@@ -89,8 +90,8 @@ Created when context is compacted. Stores a summary of earlier messages.
 ```
 
 Optional fields:
-- `details`: Compaction-implementation specific data (e.g., file operations for default implementation, or custom data for custom hook implementations)
-- `fromHook`: `true` if generated by a hook, `false`/`undefined` if pi-generated
+- `details`: Compaction-implementation specific data (e.g., file operations for default implementation, or custom data for extension implementations)
+- `fromHook`: `true` if generated by an extension, `false`/`undefined` if pi-generated
 
 ### BranchSummaryEntry
 
@@ -102,30 +103,30 @@ Created when switching branches via `/tree` with an LLM generated summary of the
 
 Optional fields:
 - `details`: File tracking data (`{ readFiles: string[], modifiedFiles: string[] }`) for default implementation, arbitrary for custom implementation
-- `fromHook`: `true` if generated by a hook
+- `fromHook`: `true` if generated by an extension
 
 ### CustomEntry
 
-Hook state persistence. Does NOT participate in LLM context.
+Extension state persistence. Does NOT participate in LLM context.
 
 ```json
-{"type":"custom","id":"h8i9j0k1","parentId":"g7h8i9j0","timestamp":"2024-12-03T14:20:00.000Z","customType":"my-hook","data":{"count":42}}
+{"type":"custom","id":"h8i9j0k1","parentId":"g7h8i9j0","timestamp":"2024-12-03T14:20:00.000Z","customType":"my-extension","data":{"count":42}}
 ```
 
-Use `customType` to identify your hook's entries on reload.
+Use `customType` to identify your extension's entries on reload.
 
 ### CustomMessageEntry
 
-Hook-injected messages that DO participate in LLM context.
+Extension-injected messages that DO participate in LLM context.
 
 ```json
-{"type":"custom_message","id":"i9j0k1l2","parentId":"h8i9j0k1","timestamp":"2024-12-03T14:25:00.000Z","customType":"my-hook","content":"Injected context...","display":true}
+{"type":"custom_message","id":"i9j0k1l2","parentId":"h8i9j0k1","timestamp":"2024-12-03T14:25:00.000Z","customType":"my-extension","content":"Injected context...","display":true}
 ```
 
 Fields:
 - `content`: String or `(TextContent | ImageContent)[]` (same as UserMessage)
-- `display`: `true` = show in TUI with purple styling, `false` = hidden
-- `details`: Optional hook-specific metadata (not sent to LLM)
+- `display`: `true` = show in TUI with distinct styling, `false` = hidden
+- `details`: Optional extension-specific metadata (not sent to LLM)
 
 ### LabelEntry
 
@@ -190,7 +191,7 @@ for (const line of lines) {
       console.log(`[${entry.id}] Custom (${entry.customType}): ${JSON.stringify(entry.data)}`);
       break;
     case "custom_message":
-      console.log(`[${entry.id}] Hook message (${entry.customType}): ${entry.content}`);
+      console.log(`[${entry.id}] Extension message (${entry.customType}): ${entry.content}`);
       break;
     case "label":
       console.log(`[${entry.id}] Label "${entry.label}" on ${entry.targetId}`);
@@ -220,18 +221,20 @@ Key methods for working with sessions programmatically:
 - `appendThinkingLevelChange(level)` - Record thinking change
 - `appendModelChange(provider, modelId)` - Record model change
 - `appendCompaction(summary, firstKeptEntryId, tokensBefore, details?, fromHook?)` - Add compaction
-- `appendCustomEntry(customType, data?)` - Hook state (not in context)
-- `appendCustomMessageEntry(customType, content, display, details?)` - Hook message (in context)
+- `appendCustomEntry(customType, data?)` - Extension state (not in context)
+- `appendCustomMessageEntry(customType, content, display, details?)` - Extension message (in context)
 - `appendLabelChange(targetId, label)` - Set/clear label
 
 ### Tree Navigation
 - `getLeafId()` - Current position
+- `getLeafEntry()` - Get current leaf entry
 - `getEntry(id)` - Get entry by ID
-- `getPath(fromId?)` - Walk from entry to root
+- `getBranch(fromId?)` - Walk from entry to root
 - `getTree()` - Get full tree structure
 - `getChildren(parentId)` - Get direct children
 - `getLabel(id)` - Get label for entry
 - `branch(entryId)` - Move leaf to earlier entry
+- `resetLeaf()` - Reset leaf to null (before any entries)
 - `branchWithSummary(entryId, summary, details?, fromHook?)` - Branch with context summary
 
 ### Context

package/docs/skills.md

@@ -37,7 +37,7 @@ Skills are loaded when:
 
 **Not a good fit for skills:**
 - "Always use TypeScript strict mode" → put in AGENTS.md
-- "Review my code" → make a slash command
+- "Review my code" → make a prompt template
 - Need user confirmation dialogs or custom TUI rendering → make a custom tool
 
 ## Skill Structure

package/docs/tui.md

@@ -343,4 +343,4 @@ Call `invalidate()` when state changes, then `handle.requestRender()` to trigger
 ## Examples
 
 - **Snake game**: [examples/hooks/snake.ts](../examples/hooks/snake.ts) - Full game with keyboard input, game loop, state persistence
-- **Custom tool rendering**: [examples/custom-tools/todo/](../examples/custom-tools/todo/) - Custom `renderCall` and `renderResult`
+- **Custom tool rendering**: [examples/extensions/todo.ts](../examples/extensions/todo.ts) - Custom `renderCall` and `renderResult`

package/examples/README.md

@@ -1,27 +1,21 @@
 # Examples
 
-Example code for pi-coding-agent SDK, hooks, and custom tools.
+Example code for pi-coding-agent SDK and extensions.
 
 ## Directories
 
 ### [sdk/](sdk/)
-Programmatic usage via `createAgentSession()`. Shows how to customize models, prompts, tools, hooks, and session management.
+Programmatic usage via `createAgentSession()`. Shows how to customize models, prompts, tools, extensions, and session management.
 
-### [hooks/](hooks/)
-Example hooks for intercepting tool calls, adding safety gates, and integrating with external systems.
-
-### [custom-tools/](custom-tools/)
-Example custom tools that extend the agent's capabilities.
-
-## Tool + Hook Combinations
-
-Some examples are designed to work together:
-
-- **todo/** - The [custom tool](custom-tools/todo/) lets the LLM manage a todo list, while the [hook](hooks/todo/) adds a `/todos` command for users to view todos at any time.
+### [extensions/](extensions/)
+Example extensions demonstrating:
+- Lifecycle event handlers (tool interception, safety gates, context modifications)
+- Custom tools (todo lists, subagents)
+- Commands and keyboard shortcuts
+- External integrations (git, file watchers)
 
 ## Documentation
 
 - [SDK Reference](sdk/README.md)
-- [Hooks Documentation](../docs/hooks.md)
-- [Custom Tools Documentation](../docs/custom-tools.md)
+- [Extensions Documentation](../docs/extensions.md)
 - [Skills Documentation](../docs/skills.md)

package/examples/extensions/README.md

@@ -0,0 +1,141 @@
+# Extension Examples
+
+Example extensions for pi-coding-agent.
+
+## Usage
+
+```bash
+# Load an extension with --extension flag
+pi --extension examples/extensions/permission-gate.ts
+
+# Or copy to extensions directory for auto-discovery
+cp permission-gate.ts ~/.pi/agent/extensions/
+```
+
+## Examples
+
+### Lifecycle & Safety
+
+| Extension | Description |
+|-----------|-------------|
+| `permission-gate.ts` | Prompts for confirmation before dangerous bash commands (rm -rf, sudo, etc.) |
+| `protected-paths.ts` | Blocks writes to protected paths (.env, .git/, node_modules/) |
+| `confirm-destructive.ts` | Confirms before destructive session actions (clear, switch, branch) |
+| `dirty-repo-guard.ts` | Prevents session changes with uncommitted git changes |
+
+### Custom Tools
+
+| Extension | Description |
+|-----------|-------------|
+| `todo.ts` | Todo list tool + `/todos` command with custom rendering and state persistence |
+| `hello.ts` | Minimal custom tool example |
+| `question.ts` | Demonstrates `ctx.ui.select()` for asking the user questions |
+| `subagent/` | Delegate tasks to specialized subagents with isolated context windows |
+
+### Commands & UI
+
+| Extension | Description |
+|-----------|-------------|
+| `plan-mode.ts` | Claude Code-style plan mode for read-only exploration with `/plan` command |
+| `tools.ts` | Interactive `/tools` command to enable/disable tools with session persistence |
+| `handoff.ts` | Transfer context to a new focused session via `/handoff <goal>` |
+| `qna.ts` | Extracts questions from last response into editor via `ctx.ui.setEditorText()` |
+| `status-line.ts` | Shows turn progress in footer via `ctx.ui.setStatus()` with themed colors |
+| `snake.ts` | Snake game with custom UI, keyboard handling, and session persistence |
+
+### Git Integration
+
+| Extension | Description |
+|-----------|-------------|
+| `git-checkpoint.ts` | Creates git stash checkpoints at each turn for code restoration on branch |
+| `auto-commit-on-exit.ts` | Auto-commits on exit using last assistant message for commit message |
+
+### System Prompt & Compaction
+
+| Extension | Description |
+|-----------|-------------|
+| `pirate.ts` | Demonstrates `systemPromptAppend` to dynamically modify system prompt |
+| `custom-compaction.ts` | Custom compaction that summarizes entire conversation |
+
+### External Dependencies
+
+| Extension | Description |
+|-----------|-------------|
+| `chalk-logger.ts` | Uses chalk from parent node_modules (demonstrates jiti module resolution) |
+| `with-deps/` | Extension with its own package.json and dependencies |
+| `file-trigger.ts` | Watches a trigger file and injects contents into conversation |
+
+## Writing Extensions
+
+See [docs/extensions.md](../../docs/extensions.md) for full documentation.
+
+```typescript
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+export default function (pi: ExtensionAPI) {
+  // Subscribe to lifecycle events
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
+      const ok = await ctx.ui.confirm("Dangerous!", "Allow rm -rf?");
+      if (!ok) return { block: true, reason: "Blocked by user" };
+    }
+  });
+
+  // Register custom tools
+  pi.registerTool({
+    name: "greet",
+    label: "Greeting",
+    description: "Generate a greeting",
+    parameters: Type.Object({
+      name: Type.String({ description: "Name to greet" }),
+    }),
+    async execute(toolCallId, params, onUpdate, ctx, signal) {
+      return {
+        content: [{ type: "text", text: `Hello, ${params.name}!` }],
+        details: {},
+      };
+    },
+  });
+
+  // Register commands
+  pi.registerCommand("hello", {
+    description: "Say hello",
+    handler: async (args, ctx) => {
+      ctx.ui.notify("Hello!", "info");
+    },
+  });
+}
+```
+
+## Key Patterns
+
+**Use StringEnum for string parameters** (required for Google API compatibility):
+```typescript
+import { StringEnum } from "@mariozechner/pi-ai";
+
+// Good
+action: StringEnum(["list", "add"] as const)
+
+// Bad - doesn't work with Google
+action: Type.Union([Type.Literal("list"), Type.Literal("add")])
+```
+
+**State persistence via details:**
+```typescript
+// Store state in tool result details for proper branching support
+return {
+  content: [{ type: "text", text: "Done" }],
+  details: { todos: [...todos], nextId },  // Persisted in session
+};
+
+// Reconstruct on session events
+pi.on("session_start", async (_event, ctx) => {
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (entry.type === "message" && entry.message.toolName === "my_tool") {
+      const details = entry.message.details;
+      // Reconstruct state from details
+    }
+  }
+});
+```

package/examples/{hooks → extensions}/auto-commit-on-exit.ts

@@ -1,13 +1,13 @@
 /**
- * Auto-Commit on Exit Hook
+ * Auto-Commit on Exit Extension
  *
  * Automatically commits changes when the agent exits.
  * Uses the last assistant message to generate a commit message.
  */
 
-import type { HookAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
-export default function (pi: HookAPI) {
+export default function (pi: ExtensionAPI) {
 	pi.on("session_shutdown", async (_event, ctx) => {
 		// Check for uncommitted changes
 		const { stdout: status, code } = await pi.exec("git", ["status", "--porcelain"]);