@mariozechner/pi-coding-agent 0.34.1 → 0.35.0

package/examples/extensions/chalk-logger.ts

@@ -0,0 +1,26 @@
+/**
+ * Example extension that uses a 3rd party dependency (chalk).
+ * Tests that jiti can resolve npm modules correctly.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import chalk from "chalk";
+
+export default function (pi: ExtensionAPI) {
+	// Log with colors using chalk
+	console.log(`${chalk.green("✓")} ${chalk.bold("chalk-logger extension loaded")}`);
+
+	pi.on("agent_start", async () => {
+		console.log(`${chalk.blue("[chalk-logger]")} Agent starting`);
+	});
+
+	pi.on("tool_call", async (event) => {
+		console.log(`${chalk.yellow("[chalk-logger]")} Tool: ${chalk.cyan(event.toolName)}`);
+		return undefined;
+	});
+
+	pi.on("agent_end", async (event) => {
+		const count = event.messages.length;
+		console.log(`${chalk.green("[chalk-logger]")} Done with ${chalk.bold(String(count))} messages`);
+	});
+}

package/examples/{hooks → extensions}/confirm-destructive.ts

@@ -1,13 +1,13 @@
 /**
- * Confirm Destructive Actions Hook
+ * Confirm Destructive Actions Extension
  *
  * Prompts for confirmation before destructive session actions (clear, switch, branch).
  * Demonstrates how to cancel session events using the before_* events.
  */
 
-import type { HookAPI, SessionBeforeSwitchEvent, SessionMessageEntry } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, SessionBeforeSwitchEvent, SessionMessageEntry } from "@mariozechner/pi-coding-agent";
 
-export default function (pi: HookAPI) {
+export default function (pi: ExtensionAPI) {
 	pi.on("session_before_switch", async (event: SessionBeforeSwitchEvent, ctx) => {
 		if (!ctx.hasUI) return;
 

package/examples/{hooks → extensions}/custom-compaction.ts

@@ -1,8 +1,8 @@
 /**
- * Custom Compaction Hook
+ * Custom Compaction Extension
  *
  * Replaces the default compaction behavior with a full summary of the entire context.
- * Instead of keeping the last 20k tokens of conversation turns, this hook:
+ * Instead of keeping the last 20k tokens of conversation turns, this extension:
  * 1. Summarizes ALL messages (messagesToSummarize + turnPrefixMessages)
  * 2. Discards all old turns completely, keeping only the summary
  *
@@ -10,16 +10,16 @@
  * which can be cheaper/faster than the main conversation model.
  *
  * Usage:
- *   pi --hook examples/hooks/custom-compaction.ts
+ *   pi --extension examples/extensions/custom-compaction.ts
  */
 
 import { complete, getModel } from "@mariozechner/pi-ai";
-import type { HookAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { convertToLlm, serializeConversation } from "@mariozechner/pi-coding-agent";
 
-export default function (pi: HookAPI) {
+export default function (pi: ExtensionAPI) {
 	pi.on("session_before_compact", async (event, ctx) => {
-		ctx.ui.notify("Custom compaction hook triggered", "info");
+		ctx.ui.notify("Custom compaction extension triggered", "info");
 
 		const { preparation, branchEntries: _, signal } = event;
 		const { messagesToSummarize, turnPrefixMessages, tokensBefore, firstKeptEntryId, previousSummary } = preparation;

package/examples/{hooks → extensions}/dirty-repo-guard.ts

@@ -1,13 +1,17 @@
 /**
- * Dirty Repo Guard Hook
+ * Dirty Repo Guard Extension
  *
  * Prevents session changes when there are uncommitted git changes.
  * Useful to ensure work is committed before switching context.
  */
 
-import type { HookAPI, HookContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 
-async function checkDirtyRepo(pi: HookAPI, ctx: HookContext, action: string): Promise<{ cancel: boolean } | undefined> {
+async function checkDirtyRepo(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	action: string,
+): Promise<{ cancel: boolean } | undefined> {
 	// Check for uncommitted changes
 	const { stdout, code } = await pi.exec("git", ["status", "--porcelain"]);
 
@@ -40,7 +44,7 @@ async function checkDirtyRepo(pi: HookAPI, ctx: HookContext, action: string): Pr
 	}
 }
 
-export default function (pi: HookAPI) {
+export default function (pi: ExtensionAPI) {
 	pi.on("session_before_switch", async (event, ctx) => {
 		const action = event.reason === "new" ? "new session" : "switch session";
 		return checkDirtyRepo(pi, ctx, action);

package/examples/{hooks → extensions}/file-trigger.ts

@@ -1,5 +1,5 @@
 /**
- * File Trigger Hook
+ * File Trigger Extension
  *
  * Watches a trigger file and injects its contents into the conversation.
  * Useful for external systems to send messages to the agent.
@@ -9,9 +9,9 @@
  */
 
 import * as fs from "node:fs";
-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_start", async (_event, ctx) => {
 		const triggerFile = "/tmp/agent-trigger.txt";
 

package/examples/{hooks → extensions}/git-checkpoint.ts

@@ -1,13 +1,13 @@
 /**
- * Git Checkpoint Hook
+ * Git Checkpoint Extension
  *
  * Creates git stash checkpoints at each turn so /branch can restore code state.
  * When branching, offers to restore code to that point in history.
  */
 
-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) {
 	const checkpoints = new Map<string, string>();
 	let currentEntryId: string | undefined;
 

package/examples/{hooks → extensions}/handoff.ts

@@ -1,5 +1,5 @@
 /**
- * Handoff hook - transfer context to a new focused session
+ * Handoff extension - transfer context to a new focused session
  *
  * Instead of compacting (which is lossy), handoff extracts what matters
  * for your next task and creates a new session with a generated prompt.
@@ -13,7 +13,7 @@
  */
 
 import { complete, type Message } from "@mariozechner/pi-ai";
-import type { HookAPI, SessionEntry } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, SessionEntry } from "@mariozechner/pi-coding-agent";
 import { BorderedLoader, convertToLlm, serializeConversation } from "@mariozechner/pi-coding-agent";
 
 const SYSTEM_PROMPT = `You are a context transfer assistant. Given a conversation history and the user's goal for a new thread, generate a focused prompt that:
@@ -38,7 +38,7 @@ Files involved:
 ## Task
 [Clear description of what to do next based on user's goal]`;
 
-export default function (pi: HookAPI) {
+export default function (pi: ExtensionAPI) {
 	pi.registerCommand("handoff", {
 		description: "Transfer context to a new focused session",
 		handler: async (args, ctx) => {

package/examples/extensions/hello.ts

@@ -0,0 +1,25 @@
+/**
+ * Hello Tool - Minimal custom tool example
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "hello",
+		label: "Hello",
+		description: "A simple greeting tool",
+		parameters: Type.Object({
+			name: Type.String({ description: "Name to greet" }),
+		}),
+
+		async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
+			const { name } = params as { name: string };
+			return {
+				content: [{ type: "text", text: `Hello, ${name}!` }],
+				details: { greeted: name },
+			};
+		},
+	});
+}

package/examples/{hooks → extensions}/permission-gate.ts

@@ -1,13 +1,13 @@
 /**
- * Permission Gate Hook
+ * Permission Gate Extension
  *
  * Prompts for confirmation before running potentially dangerous bash commands.
  * Patterns checked: rm -rf, sudo, chmod/chown 777
  */
 
-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) {
 	const dangerousPatterns = [/\brm\s+(-rf?|--recursive)/i, /\bsudo\b/i, /\b(chmod|chown)\b.*777/i];
 
 	pi.on("tool_call", async (event, ctx) => {

package/examples/{hooks → extensions}/pirate.ts

@@ -1,18 +1,18 @@
 /**
- * Pirate Hook
+ * Pirate Extension
  *
  * Demonstrates using systemPromptAppend in before_agent_start to dynamically
- * modify the system prompt based on hook state.
+ * modify the system prompt based on extension state.
  *
  * Usage:
- * 1. Copy this file to ~/.pi/agent/hooks/ or your project's .pi/hooks/
+ * 1. Copy this file to ~/.pi/agent/extensions/ or your project's .pi/extensions/
  * 2. Use /pirate to toggle pirate mode
  * 3. When enabled, the agent will respond like a pirate
  */
 
-import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
-export default function pirateHook(pi: HookAPI) {
+export default function pirateExtension(pi: ExtensionAPI) {
 	let pirateMode = false;
 
 	// Register /pirate command to toggle pirate mode

package/examples/{hooks → extensions}/plan-mode.ts

@@ -1,5 +1,5 @@
 /**
- * Plan Mode Hook
+ * Plan Mode Extension
  *
  * Provides a Claude Code-style "plan mode" for safe code exploration.
  * When enabled, the agent can only use read-only tools and cannot modify files.
@@ -14,12 +14,12 @@
  * - Uses ID-based tracking: agent outputs [DONE:id] to mark steps complete
  *
  * Usage:
- * 1. Copy this file to ~/.pi/agent/hooks/ or your project's .pi/hooks/
+ * 1. Copy this file to ~/.pi/agent/extensions/ or your project's .pi/extensions/
  * 2. Use /plan to toggle plan mode on/off
  * 3. Or start in plan mode with --plan flag
  */
 
-import type { HookAPI, HookContext } from "@mariozechner/pi-coding-agent/hooks";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import { Key } from "@mariozechner/pi-tui";
 
 // Read-only tools for plan mode
@@ -207,7 +207,7 @@ function extractTodoItems(message: string): TodoItem[] {
 	return items;
 }
 
-export default function planModeHook(pi: HookAPI) {
+export default function planModeExtension(pi: ExtensionAPI) {
 	let planModeEnabled = false;
 	let toolsCalledThisTurn = false;
 	let executionMode = false;
@@ -221,7 +221,7 @@ export default function planModeHook(pi: HookAPI) {
 	});
 
 	// Helper to update status displays
-	function updateStatus(ctx: HookContext) {
+	function updateStatus(ctx: ExtensionContext) {
 		if (executionMode && todoItems.length > 0) {
 			const completed = todoItems.filter((t) => t.completed).length;
 			ctx.ui.setStatus("plan-mode", ctx.ui.theme.fg("accent", `📋 ${completed}/${todoItems.length}`));
@@ -249,7 +249,7 @@ export default function planModeHook(pi: HookAPI) {
 		}
 	}
 
-	function togglePlanMode(ctx: HookContext) {
+	function togglePlanMode(ctx: ExtensionContext) {
 		planModeEnabled = !planModeEnabled;
 		executionMode = false;
 		todoItems = [];

package/examples/{hooks → extensions}/protected-paths.ts

@@ -1,13 +1,13 @@
 /**
- * Protected Paths Hook
+ * Protected Paths Extension
  *
  * Blocks write and edit operations to protected paths.
  * Useful for preventing accidental modifications to sensitive files.
  */
 
-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) {
 	const protectedPaths = [".env", ".git/", "node_modules/"];
 
 	pi.on("tool_call", async (event, ctx) => {

package/examples/{hooks → extensions}/qna.ts

@@ -1,5 +1,5 @@
 /**
- * Q&A extraction hook - extracts questions from assistant responses
+ * Q&A extraction extension - extracts questions from assistant responses
  *
  * Demonstrates the "prompt generator" pattern:
  * 1. /qna command gets the last assistant message
@@ -8,7 +8,7 @@
  */
 
 import { complete, type UserMessage } from "@mariozechner/pi-ai";
-import type { HookAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { BorderedLoader } from "@mariozechner/pi-coding-agent";
 
 const SYSTEM_PROMPT = `You are a question extractor. Given text from a conversation, extract any questions that need answering and format them for the user to fill in.
@@ -27,7 +27,7 @@ A:
 
 Keep questions in the order they appeared. Be concise.`;
 
-export default function (pi: HookAPI) {
+export default function (pi: ExtensionAPI) {
 	pi.registerCommand("qna", {
 		description: "Extract questions from last assistant message into editor",
 		handler: async (_args, ctx) => {

package/examples/{custom-tools/question/index.ts → extensions/question.ts}

@@ -2,7 +2,7 @@
  * Question Tool - Let the LLM ask the user a question with options
  */
 
-import type { CustomTool, CustomToolFactory } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
 
@@ -17,40 +17,40 @@ const QuestionParams = Type.Object({
 	options: Type.Array(Type.String(), { description: "Options for the user to choose from" }),
 });
 
-const factory: CustomToolFactory = (pi) => {
-	const tool: CustomTool<typeof QuestionParams, QuestionDetails> = {
+export default function (pi: ExtensionAPI) {
+	pi.registerTool({
 		name: "question",
 		label: "Question",
 		description: "Ask the user a question and let them pick from options. Use when you need user input to proceed.",
 		parameters: QuestionParams,
 
-		async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
-			if (!pi.hasUI) {
+		async execute(_toolCallId, params, _onUpdate, ctx, _signal) {
+			if (!ctx.hasUI) {
 				return {
 					content: [{ type: "text", text: "Error: UI not available (running in non-interactive mode)" }],
-					details: { question: params.question, options: params.options, answer: null },
+					details: { question: params.question, options: params.options, answer: null } as QuestionDetails,
 				};
 			}
 
 			if (params.options.length === 0) {
 				return {
 					content: [{ type: "text", text: "Error: No options provided" }],
-					details: { question: params.question, options: [], answer: null },
+					details: { question: params.question, options: [], answer: null } as QuestionDetails,
 				};
 			}
 
-			const answer = await pi.ui.select(params.question, params.options);
+			const answer = await ctx.ui.select(params.question, params.options);
 
 			if (answer === undefined) {
 				return {
 					content: [{ type: "text", text: "User cancelled the selection" }],
-					details: { question: params.question, options: params.options, answer: null },
+					details: { question: params.question, options: params.options, answer: null } as QuestionDetails,
 				};
 			}
 
 			return {
 				content: [{ type: "text", text: `User selected: ${answer}` }],
-				details: { question: params.question, options: params.options, answer },
+				details: { question: params.question, options: params.options, answer } as QuestionDetails,
 			};
 		},
 
@@ -63,7 +63,7 @@ const factory: CustomToolFactory = (pi) => {
 		},
 
 		renderResult(result, _options, theme) {
-			const { details } = result;
+			const details = result.details as QuestionDetails | undefined;
 			if (!details) {
 				const text = result.content[0];
 				return new Text(text?.type === "text" ? text.text : "", 0, 0);
@@ -75,9 +75,5 @@ const factory: CustomToolFactory = (pi) => {
 
 			return new Text(theme.fg("success", "✓ ") + theme.fg("accent", details.answer), 0, 0);
 		},
-	};
-
-	return tool;
-};
-
-export default factory;
+	});
+}

package/examples/{hooks → extensions}/snake.ts

@@ -1,8 +1,8 @@
 /**
- * Snake game hook - play snake with /snake command
+ * Snake game extension - play snake with /snake command
  */
 
-import type { HookAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { matchesKey, visibleWidth } from "@mariozechner/pi-tui";
 
 const GAME_WIDTH = 40;
@@ -306,7 +306,7 @@ class SnakeComponent {
 
 const SNAKE_SAVE_TYPE = "snake-save";
 
-export default function (pi: HookAPI) {
+export default function (pi: ExtensionAPI) {
 	pi.registerCommand("snake", {
 		description: "Play Snake!",
 

package/examples/{hooks → extensions}/status-line.ts

@@ -1,13 +1,13 @@
 /**
- * Status Line Hook
+ * Status Line Extension
  *
  * Demonstrates ctx.ui.setStatus() for displaying persistent status text in the footer.
  * Shows turn progress with themed colors.
  */
 
-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) {
 	let turnCount = 0;
 
 	pi.on("session_start", async (_event, ctx) => {

package/examples/{custom-tools → extensions}/subagent/README.md

@@ -16,14 +16,14 @@ Delegate tasks to specialized subagents with isolated context windows.
 ```
 subagent/
 ├── README.md            # This file
-├── index.ts             # The custom tool (entry point)
+├── index.ts             # The extension (entry point)
 ├── agents.ts            # Agent discovery logic
 ├── agents/              # Sample agent definitions
 │   ├── scout.md         # Fast recon, returns compressed context
 │   ├── planner.md       # Creates implementation plans
 │   ├── reviewer.md      # Code review
 │   └── worker.md        # General-purpose (full capabilities)
-└── commands/            # Workflow presets
+└── prompts/             # Workflow presets (prompt templates)
     ├── implement.md     # scout -> planner -> worker
     ├── scout-and-plan.md    # scout -> planner (no implementation)
     └── implement-and-review.md  # worker -> reviewer -> worker
@@ -34,21 +34,21 @@ subagent/
 From the repository root, symlink the files:
 
 ```bash
-# Symlink the tool (must be in a subdirectory with index.ts)
-mkdir -p ~/.pi/agent/tools/subagent
-ln -sf "$(pwd)/packages/coding-agent/examples/custom-tools/subagent/index.ts" ~/.pi/agent/tools/subagent/index.ts
-ln -sf "$(pwd)/packages/coding-agent/examples/custom-tools/subagent/agents.ts" ~/.pi/agent/tools/subagent/agents.ts
+# Symlink the extension (must be in a subdirectory with index.ts)
+mkdir -p ~/.pi/agent/extensions/subagent
+ln -sf "$(pwd)/packages/coding-agent/examples/extensions/subagent/index.ts" ~/.pi/agent/extensions/subagent/index.ts
+ln -sf "$(pwd)/packages/coding-agent/examples/extensions/subagent/agents.ts" ~/.pi/agent/extensions/subagent/agents.ts
 
 # Symlink agents
 mkdir -p ~/.pi/agent/agents
-for f in packages/coding-agent/examples/custom-tools/subagent/agents/*.md; do
+for f in packages/coding-agent/examples/extensions/subagent/agents/*.md; do
   ln -sf "$(pwd)/$f" ~/.pi/agent/agents/$(basename "$f")
 done
 
-# Symlink workflow commands
-mkdir -p ~/.pi/agent/commands
-for f in packages/coding-agent/examples/custom-tools/subagent/commands/*.md; do
-  ln -sf "$(pwd)/$f" ~/.pi/agent/commands/$(basename "$f")
+# Symlink workflow prompts
+mkdir -p ~/.pi/agent/prompts
+for f in packages/coding-agent/examples/extensions/subagent/prompts/*.md; do
+  ln -sf "$(pwd)/$f" ~/.pi/agent/prompts/$(basename "$f")
 done
 ```
 
@@ -81,7 +81,7 @@ Run 2 scouts in parallel: one to find models, one to find providers
 Use a chain: first have scout find the read tool, then have planner suggest improvements
 ```
 
-### Workflow commands
+### Workflow prompts
 ```
 /implement add Redis caching to the session store
 /scout-and-plan refactor auth to support OAuth
@@ -150,10 +150,10 @@ Project agents override user agents with the same name when `agentScope: "both"`
 | `reviewer` | Code review | Sonnet | read, grep, find, ls, bash |
 | `worker` | General-purpose | Sonnet | (all default) |
 
-## Workflow Commands
+## Workflow Prompts
 
-| Command | Flow |
-|---------|------|
+| Prompt | Flow |
+|--------|------|
 | `/implement <query>` | scout → planner → worker |
 | `/scout-and-plan <query>` | scout → planner |
 | `/implement-and-review <query>` | worker → reviewer → worker |