@aliou/pi-dev-kit 0.6.0 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-dev-kit",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "license": "MIT",
   "type": "module",
   "private": false,
@@ -39,14 +39,14 @@
     "@sinclair/typebox": "^0.34.41"
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "0.64.0",
-    "@mariozechner/pi-tui": "0.64.0"
+    "@mariozechner/pi-coding-agent": "0.65.2",
+    "@mariozechner/pi-tui": "0.65.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.13",
     "@changesets/cli": "^2.27.11",
-    "@mariozechner/pi-coding-agent": "0.64.0",
-    "@mariozechner/pi-tui": "0.64.0",
+    "@mariozechner/pi-coding-agent": "0.65.2",
+    "@mariozechner/pi-tui": "0.65.2",
     "@types/node": "^25.0.10",
     "husky": "^9.1.7",
     "typescript": "^5.9.3"

package/src/skills/pi-extension/SKILL.md

@@ -11,10 +11,10 @@ Guide for creating and maintaining Pi extensions. Read the relevant reference fi
 
 Pi injects these packages via jiti at runtime. Extensions do not need to install them — they are available as peer dependencies:
 
-- `@mariozechner/pi-coding-agent` — core types, utilities, `Type`/`Static` (re-exported from TypeBox)
+- `@mariozechner/pi-coding-agent` — core types, utilities, and extension APIs
 - `@mariozechner/pi-tui` — TUI components
 - `@mariozechner/pi-ai` — AI utilities (`StringEnum`, etc.)
-- `@sinclair/typebox` — schema definitions (also re-exported from `pi-coding-agent`, prefer the re-export)
+- `@sinclair/typebox` — schema definitions for tool parameters and related types
 
 ```typescript
 // Tool UI components (from @aliou/pi-utils-ui)
@@ -53,7 +53,7 @@ import { Container, Markdown, Text } from "@mariozechner/pi-tui";
 6. If the extension tracks state: Read `references/state.md`.
 7. For less common APIs: Read `references/additional-apis.md`.
 8. If the extension has user-configurable settings: Use `registerSettingsCommand` from `@aliou/pi-utils-settings`. Read `references/structure.md` for settings command and auth wizard patterns.
-9. If the extension adds a tool that competes with a natural bash fallback: use `promptSnippet` and `promptGuidelines` on the tool definition for simple guidance. Use system prompt hooks only for complex cross-tool orchestration. Read the **Guidance** section in `references/additional-apis.md`.
+9. If the extension adds a tool that competes with a natural bash fallback: use `promptSnippet` and `promptGuidelines` on the tool definition for simple guidance. Write `promptGuidelines` as standalone bullets that name the exact tool, because pi injects them verbatim into the shared global `Guidelines` section. Use system prompt hooks only for complex cross-tool orchestration. Read the **Guidance** section in `references/additional-apis.md`.
 10. Before publishing: Read `references/publish.md` and `references/documentation.md`.
 
 ### Modifying an Existing Extension
@@ -68,11 +68,11 @@ import { Container, Markdown, Text } from "@mariozechner/pi-tui";
 | File | Content |
 |---|---|
 | `references/structure.md` | Project layout, package.json, tsconfig, biome.json, config.ts, entry point patterns (including acceptable exceptions), API key pattern, imports |
-| `references/tools.md` | Tool registration, execute signature, parameters, streaming, rendering, naming, renderCall/renderResult UI guidelines |
+| `references/tools.md` | Tool registration, execute signature, parameters, `prepareArguments`, path normalization, file mutation queueing, streaming, rendering, naming, renderCall/renderResult UI guidelines |
 | `references/hooks.md` | Events, blocking/cancelling, input transformation, system prompt modification, bash spawn hooks (command rewriting) |
 | `references/commands.md` | Command registration, three-tier pattern, component extraction |
 | `references/components.md` | TUI components (pi-tui + pi-coding-agent), custom(), theme styling, keyboard handling |
-| `references/providers.md` | Provider registration, model definition, compat field, API key gating |
+| `references/providers.md` | Current `pi.registerProvider(name, config)` API, model definition, provider override/registration patterns, API key gating |
 | `references/modes.md` | Mode behavior matrix, ctx.hasUI, dialog vs fire-and-forget, three-tier pattern |
 | `references/messages.md` | sendMessage, registerMessageRenderer, notify, when to use each |
 | `references/state.md` | appendEntry, state reconstruction, appendEntry vs sendMessage |
@@ -105,11 +105,11 @@ When implementing, look at these existing extensions for patterns:
 9. **Long args placement**: Put long prompt/task/question/context strings on following lines. Keep first line scannable.
 10. **Result layout**: In `renderResult(result, options, theme)`, handle `isPartial` first with a stable tool-scoped message. Detect errors by checking for missing expected fields in `details` (framework sets `details: {}` on throw). Use `ToolBody` from `@aliou/pi-utils-ui` with `showCollapsed` fields. Use `ToolFooter` conditionally (omit when empty). Use `Container`/`Markdown` for rich content.
 11. **Typed param alias**: Define `type MyToolParams = Static<typeof parameters>` at the top of each tool file. Use it everywhere instead of repeating `Static<typeof parameters>`.
-12. **Tool metadata**: Every tool must have `label` (required). Add `promptSnippet` for system prompt tool listing. Add `promptGuidelines` for usage instructions. These replace system-prompt hooks for simple tools.
+12. **Tool metadata**: Every tool must have `label` (required). Add `promptSnippet` for system prompt tool listing. Add `promptGuidelines` for usage instructions, but write them as standalone global bullets that name the exact tool. These replace system-prompt hooks for simple tools.
 13. **Output truncation**: For tools returning large text, use `truncateHead()` from `@mariozechner/pi-coding-agent`. Write full content to temp file. Append footer with line/byte counts and temp file path.
 14. **Core/lib pattern**: Extract domain logic into modules (`client.ts`, `manager.ts`) that don't import from Pi. Tools are thin wrappers. Core modules are unit-testable with vitest.
 15. **Humanize messages**: Show display names first, IDs in dim/parens. `"Started \"backend\" (proc_42)"` not `"Started proc_42"`.
-16. **peerDependencies**: Pi injects `@mariozechner/pi-coding-agent`, `@mariozechner/pi-tui`, `@mariozechner/pi-ai`, and `@sinclair/typebox` via jiti at runtime. Any of these that your extension imports must be listed in `peerDependencies` with `optional: true` in `peerDependenciesMeta`. Without `optional: true`, npm 7+ auto-installs peers, adding hundreds of packages on every install even though Pi already provides them. Keep them in `devDependencies` too for local type checking — `pnpm install` installs peers, so development is unaffected. Use `>=CURRENT_VERSION` range, not `*`. Prefer importing `Type`/`Static` from `@mariozechner/pi-coding-agent` rather than `@sinclair/typebox` directly.
+16. **peerDependencies**: Pi injects `@mariozechner/pi-coding-agent`, `@mariozechner/pi-tui`, `@mariozechner/pi-ai`, and `@sinclair/typebox` via jiti at runtime. Any of these that your extension imports must be listed in `peerDependencies` with `optional: true` in `peerDependenciesMeta`. Without `optional: true`, npm 7+ auto-installs peers, adding hundreds of packages on every install even though Pi already provides them. Keep them in `devDependencies` too for local type checking — `pnpm install` installs peers, so development is unaffected. Use `>=CURRENT_VERSION` range, not `*`.
 17. **Check existing components**: Before creating a new TUI component, check if `pi-tui` or `pi-coding-agent` already exports one that fits.
 18. **Forward abort signals**: Always pass `signal` through to `fetch()`, `pi.exec()`, and API client methods. A tool that ignores its signal prevents cancellation from reaching the underlying operation. Never prefix with `_signal` unless the tool truly has no async work to cancel.
 19. **Never use Node child_process APIs**: Do not use `child_process.exec`, `execSync`, `spawn`, `spawnSync`, `execFile`, or `execFileSync` to run binaries or shell scripts. Always use `pi.exec()`. `pi.exec` handles CWD, signal propagation, and output capture consistently. The only exception is if you need a long-lived streaming process with stdin/stdout piping that `pi.exec` cannot support — document the reason in code comments.
@@ -133,9 +133,12 @@ Before considering an extension complete:
 - [ ] `renderResult` uses `ToolBody` with `showCollapsed` fields.
 - [ ] `renderResult` uses `ToolFooter` conditionally (omits when empty).
 - [ ] Every tool has `label` field.
-- [ ] Tools have `promptSnippet` and/or `promptGuidelines` when appropriate.
+- [ ] Tools have `promptSnippet` and/or `promptGuidelines` when appropriate, and `promptGuidelines` bullets name the exact tool instead of saying `this tool`.
 - [ ] Large output tools use `truncateHead()` + temp file pattern.
 - [ ] Domain logic is extracted to testable core modules.
+- [ ] File-mutating custom tools use `withFileMutationQueue()` for the full read-modify-write window.
+- [ ] Path-taking custom tools normalize a leading `@` before resolving paths.
+- [ ] Tool overrides re-declare `promptSnippet`/`promptGuidelines` if they need inherited prompt behavior.
 - [ ] `ctx.ui.custom()` calls have RPC fallback, and interactive close/cancel paths do not rely on `done(undefined)` when fallback detection uses `result === undefined`.
 - [ ] `tool_call` hooks check `ctx.hasUI` before dialog methods.
 - [ ] Fire-and-forget methods (notify, setStatus, etc.) are used without hasUI guards.

package/src/skills/pi-extension/references/additional-apis.md

@@ -136,7 +136,7 @@ There are two ways to inject guidance, depending on complexity:
 For most tools, use the SDK-level `promptSnippet` and `promptGuidelines` fields directly on the tool definition. No hook is needed.
 
 - **`promptSnippet`** — Injected into the "Available tools" system prompt section. Use for a concise (1–2 sentence) description of when to prefer this tool.
-- **`promptGuidelines`** — Appended to the "Guidelines" section. Use for a short list of usage rules.
+- **`promptGuidelines`** — Appended verbatim to the global "Guidelines" section. Use for a short list of usage rules that still make sense without extra tool-local context.
 
 ```typescript
 const myTool = {
@@ -145,8 +145,8 @@ const myTool = {
   description: "...",
   promptSnippet: "Manage background processes without blocking the conversation.",
   promptGuidelines: [
-    "Use this tool for long-running commands instead of bash.",
-    "After starting a process, continue other work instead of waiting.",
+    "Use my_tool for long-running commands instead of bash.",
+    "After starting my_tool, continue other work instead of waiting.",
   ],
   parameters: ...,
   execute: ...,
@@ -155,6 +155,8 @@ const myTool = {
 
 This is the simplest approach and works well when guidance is specific to a single tool.
 
+Because these bullets are merged into the shared global `Guidelines` section, avoid vague phrasing like `Use this tool...`. Name the exact tool (`my_tool`, `process`, `linkup_web_search`) so the bullet remains clear after injection.
+
 #### Tier 2: System Prompt Hook (For Complex Cross-Tool Orchestration)
 
 Use the `before_agent_start` hook when:

package/src/skills/pi-extension/references/hooks.md

@@ -8,13 +8,11 @@ Hooks let extensions react to lifecycle events. They are registered with `pi.on(
 
 | Event | When | Can Cancel | Payload |
 |---|---|---|---|
-| `session_start` | New session created | No | `{}` |
-| `session_switch` | Switched to different session | No | `{ reason: "new" \| "switch" \| "fork" }` |
-| `session_before_switch` | Before switching sessions | Yes (`{ cancel: true }`) | `{ reason: "new" \| "switch" \| "fork" }` |
-| `session_before_fork` | Before forking a session | Yes (`{ cancel: true }`) | `{}` |
-| `session_fork` | After session was forked | No | `{}` |
-| `session_shutdown` | Pi is shutting down | No | `{}` |
-| `session_before_compact` | Before compaction | Yes (return custom summary string) | `{ summary: string }` |
+| `session_start` | Session starts, reloads, or is replaced | No | `{ reason: "startup" \| "reload" \| "new" \| "resume" \| "fork", previousSessionFile? }` |
+| `session_before_switch` | Before `/new` or `/resume` replaces the current session | Yes (`{ cancel: true }`) | `{ reason: "new" \| "resume", targetSessionFile? }` |
+| `session_before_fork` | Before forking a session | Yes (`{ cancel: true }`) | `{ entryId }` |
+| `session_shutdown` | Current session runtime is shutting down or being replaced | No | `{}` |
+| `session_before_compact` | Before compaction | Yes (cancel or provide custom compaction) | event-specific compaction data |
 
 ### Agent Events
 
@@ -98,8 +96,13 @@ pi.on("session_before_switch", async (event, ctx) => {
 
 ```typescript
 pi.on("session_before_compact", async (event, ctx) => {
-  // Return a custom summary string to replace the default compaction
-  return `Custom summary: ${event.summary.slice(0, 200)}...`;
+  return {
+    compaction: {
+      summary: "Custom summary",
+      firstKeptEntryId: event.preparation.firstKeptEntryId,
+      tokensBefore: event.preparation.tokensBefore,
+    },
+  };
 });
 ```
 

package/src/skills/pi-extension/references/providers.md

@@ -1,134 +1,159 @@
 # Providers
 
-Providers add LLM backends to pi. They connect pi to model APIs (OpenAI-compatible or custom).
+Providers add LLM backends to pi. They connect pi to model APIs, proxies, gateways, and custom streaming implementations.
+
+This reference tracks the current `pi.registerProvider(name, config)` API from pi-mono. For full provider details and advanced examples, also read pi-mono `packages/coding-agent/docs/custom-provider.md`.
 
 ## Registration
 
 ```typescript
-import { Type, type ExtensionAPI, type ProviderDefinition } from "@mariozechner/pi-coding-agent";
-
-const myProvider: ProviderDefinition = {
-  name: "my-provider",
-  models: () => {
-    const apiKey = process.env.MY_API_KEY;
-    if (!apiKey) return [];
-
-    return [
-      {
-        id: "my-provider/model-name",
-        name: "Model Name",
-        provider: "my-provider",
-        canStream: true,
-        contextLength: 128000,
-        maxOutputTokens: 8192,
-        pricing: { inputPerMillion: 3.0, outputPerMillion: 15.0 },
-        compat: {
-          type: "openai-completions",
-          maxTokensField: "max_tokens",
-          supportsDeveloperRole: false,
-        },
-      },
-    ];
-  },
-  apiKey: () => process.env.MY_API_KEY,
-  baseUrl: () => "https://api.my-provider.com/v1",
+import type { ExtensionAPI, ProviderConfig } from "@mariozechner/pi-coding-agent";
+
+const myProviderConfig: ProviderConfig = {
+  baseUrl: "https://api.example.com/v1",
+  apiKey: "MY_API_KEY",
+  api: "openai-completions",
+  models: [
+    {
+      id: "my-model",
+      name: "My Model",
+      reasoning: false,
+      input: ["text", "image"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: 128000,
+      maxTokens: 4096,
+    },
+  ],
 };
 
 export default function (pi: ExtensionAPI) {
-  pi.registerProvider(myProvider);
+  pi.registerProvider("my-provider", myProviderConfig);
 }
 ```
 
-## Provider Definition
+## Common Registration Patterns
 
-| Field | Type | Description |
-|---|---|---|
-| `name` | `string` | Unique provider identifier. Used as prefix in model IDs. |
-| `models` | `() => ProviderModelConfig[]` | Returns available models. Called when pi needs the model list. Return `[]` if the API key is missing. |
-| `apiKey` | `() => string \| undefined` | Returns the API key. Pi calls this when making requests. |
-| `baseUrl` | `() => string \| undefined` | Returns the base URL for the API. |
+### Override an existing provider
 
-The `models` function is the right place to check for API key presence. If the key is missing, return an empty array and the provider will appear registered but offer no models.
-
-## Model Definition
+```typescript
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
-| Field | Type | Description |
-|---|---|---|
-| `id` | `string` | Unique model ID. Convention: `provider/model-name`. |
-| `name` | `string` | Display name shown in model picker. |
-| `provider` | `string` | Must match the provider's `name`. |
-| `canStream` | `boolean` | Whether the model supports streaming responses. |
-| `contextLength` | `number` | Maximum context window in tokens. |
-| `maxOutputTokens` | `number` | Maximum output tokens per response. |
-| `pricing` | `object` | `{ inputPerMillion, outputPerMillion }` in USD. Used for cost display. |
-| `compat` | `object` | OpenAI compatibility settings. See below. |
+export default function (pi: ExtensionAPI) {
+  pi.registerProvider("anthropic", {
+    baseUrl: "https://proxy.example.com",
+  });
+}
+```
 
-## Compat Field
+Use this when you want to keep the built-in provider and model list, but change the endpoint and/or headers.
 
-The `compat` field tells pi how to talk to the model's API. Most third-party APIs are OpenAI-compatible but differ in which features they support.
+### Register a new provider
 
 ```typescript
-compat: {
-  type: "openai-completions",
-
-  // Which field name the API uses for max output tokens
-  maxTokensField: "max_tokens" | "max_completion_tokens",
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
-  // Whether the API supports the 'developer' role (vs 'system')
-  supportsDeveloperRole: boolean,
-
-  // Whether the API supports the 'store' parameter
-  supportsStore: boolean,
+export default function (pi: ExtensionAPI) {
+  pi.registerProvider("my-provider", {
+    baseUrl: "https://api.example.com/v1",
+    apiKey: "MY_API_KEY",
+    api: "openai-completions",
+    models: [
+      {
+        id: "my-model",
+        name: "My Model",
+        reasoning: false,
+        input: ["text"],
+        cost: { input: 0.5, output: 1.5, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 128000,
+        maxTokens: 8192,
+      },
+    ],
+  });
+}
+```
 
-  // Whether the API supports reasoning_effort parameter
-  supportsReasoningEffort: boolean,
+### Unregister a provider
 
-  // Whether usage stats are included in streaming responses
-  supportsUsageInStreaming: boolean,
+```typescript
+pi.unregisterProvider("my-provider");
+```
 
-  // Whether tool results must include a 'name' field
-  requiresToolResultName: boolean,
+This takes effect immediately at runtime.
 
-  // Whether an assistant message is required after tool results
-  requiresAssistantAfterToolResult: boolean,
+## ProviderConfig Fields
 
-  // Whether thinking/reasoning must be sent as text content
-  requiresThinkingAsText: boolean,
+| Field | Type | Description |
+|---|---|---|
+| `baseUrl` | `string` | Base URL for the provider or proxy. |
+| `headers` | `Record<string, string>` | Optional static headers to add to requests. |
+| `apiKey` | `string` | Environment variable name containing the API key. |
+| `api` | `"openai-completions" \| "openai-responses"` | Compatibility mode for request/response handling. |
+| `models` | `ProviderModelConfig[]` | Model definitions exposed by this provider. |
+| `streamSimple` | `function` | Optional custom streaming implementation for non-standard APIs. |
+| `oauth` | `object` | Optional OAuth config for providers that need browser-based auth. |
 
-  // Mistral-specific tool ID requirements
-  requiresMistralToolIds: boolean,
+Use the built-in OpenAI-compatible path when possible. Reach for `streamSimple` only when the upstream API is not compatible enough.
 
-  // Format for thinking/reasoning blocks
-  thinkingFormat: "openai" | "zai" | "qwen",
+## Model Definition
 
-  // OpenRouter-specific routing hints
-  openRouterRouting: object,
+The exact model type has more fields, but these are the ones you will usually need:
 
-  // Vercel AI Gateway routing
-  vercelGatewayRouting: object,
-}
-```
+| Field | Type | Description |
+|---|---|---|
+| `id` | `string` | Model identifier within the provider config. |
+| `name` | `string` | Display name shown in model selection UI. |
+| `reasoning` | `boolean` | Whether the model is a reasoning model. |
+| `input` | `Array<"text" \| "image" \| "audio" \| "pdf">` | Input modalities supported by the model. |
+| `cost` | `object` | `{ input, output, cacheRead, cacheWrite }` cost values. |
+| `contextWindow` | `number` | Maximum context window. |
+| `maxTokens` | `number` | Maximum output tokens. |
 
-All fields in `compat` are optional except `type`. Start with the minimum and add fields as needed based on API behavior.
+## API Key Gating
 
-There is also `type: "openai-responses"` for providers using the OpenAI Responses API, which currently has no additional compat fields.
+Provider registration and extension tool registration are separate concerns.
 
-## Provider with API Key Gate
+For providers:
+- Register the provider with `pi.registerProvider(name, config)`.
+- Point `apiKey` at the environment variable name that holds the credential.
+- If the provider should exist even when tools are disabled, still register it.
 
-Register the provider unconditionally but gate tools/commands on the API key:
+For tools and commands that require the same credential:
+- Gate those registrations separately in your extension entry point.
 
 ```typescript
 export default function (pi: ExtensionAPI) {
-  // Provider always registered -- models() returns [] if no key
-  pi.registerProvider(myProvider);
+  pi.registerProvider("my-provider", {
+    baseUrl: "https://api.example.com/v1",
+    apiKey: "MY_API_KEY",
+    api: "openai-completions",
+    models: [
+      {
+        id: "my-model",
+        name: "My Model",
+        reasoning: false,
+        input: ["text"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 128000,
+        maxTokens: 4096,
+      },
+    ],
+  });
 
-  const apiKey = process.env.MY_API_KEY;
-  if (!apiKey) return;
+  if (!process.env.MY_API_KEY) return;
 
-  // Only register tools that need the key
-  pi.registerTool(createSearchTool(apiKey));
-  pi.registerCommand(createQuotasCommand(apiKey));
+  pi.registerTool(mySearchTool);
+  pi.registerCommand("quota", { handler: showQuota });
 }
 ```
 
-This way the provider appears in pi's provider list even without a key, and users see a clear "no models available" state rather than a missing provider.
+That pattern keeps provider setup accurate while still hiding tools that cannot work without credentials.
+
+## When to read the upstream docs
+
+Also read pi-mono `packages/coding-agent/docs/custom-provider.md` when you need:
+- custom streaming via `streamSimple`
+- OAuth support
+- proxying existing providers
+- header injection
+- provider teardown with `pi.unregisterProvider()`
+- advanced model config details

package/src/skills/pi-extension/references/state.md

@@ -1,42 +1,53 @@
 # State Management
 
-Extensions can persist state in the session history using `appendEntry`. State is reconstructed by replaying entries when a session is loaded.
+Extensions can persist state in the session history. In modern Pi extensions, the usual pattern is to store reconstructible state in tool result `details` and rebuild it from the current branch on `session_start`.
 
-## appendEntry
+## Recommended Pattern: Store State in Tool Result Details
 
-Adds an entry to the session conversation. Unlike `sendMessage`, entries from `appendEntry` are explicitly for state tracking and are rendered via the tool result rendering system.
+When a tool changes extension state, return the latest state in `details`. That keeps the state aligned with normal tool history, branching, and reconstruction.
 
 ```typescript
-pi.appendEntry({
-  toolName: "todo",
-  toolCallId: `todo-${Date.now()}`,
-  input: { action: "add", text: "Buy groceries" },
-  output: "Added: Buy groceries",
-  display: true,
-  details: { items: ["Buy groceries"] },
-});
-```
+export default function (pi: ExtensionAPI) {
+  let items: string[] = [];
 
-| Field | Type | Description |
-|---|---|---|
-| `toolName` | `string` | Which tool this entry is associated with. Used for rendering. |
-| `toolCallId` | `string` | Unique ID for this entry. |
-| `input` | `object` | The "input" shown in the entry (as if the tool was called with these params). |
-| `output` | `string` | The text output (what the LLM sees). |
-| `display` | `boolean` | Whether to show in TUI. |
-| `details` | `object` | Rich data for the tool's `renderResult`. |
+  pi.on("session_start", async (_event, ctx) => {
+    items = [];
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type === "message" && entry.message.role === "toolResult") {
+        if (entry.message.toolName === "todo") {
+          items = entry.message.details?.items ?? [];
+        }
+      }
+    }
+  });
+
+  pi.registerTool({
+    name: "todo",
+    // ...
+    async execute() {
+      items.push("Buy groceries");
+      return {
+        content: [{ type: "text", text: "Added todo item" }],
+        details: { items: [...items] },
+      };
+    },
+  });
+}
+```
 
 ## Reconstructing State from Session
 
-When a session loads, you can reconstruct state by iterating over existing entries. This is typically done in a `session_start` or `session_switch` handler:
+When a session loads, reconstruct state in `session_start` by iterating over the current branch or full session through `ctx.sessionManager`:
 
 ```typescript
 pi.on("session_start", async (_event, ctx) => {
-  // Rebuild state from session entries
-  const entries = ctx.getEntries();
-  for (const entry of entries) {
-    if (entry.toolName === "todo" && entry.details) {
-      todoItems = entry.details.items;
+  todoItems = [];
+
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (entry.type === "message" && entry.message.role === "toolResult") {
+      if (entry.message.toolName === "todo") {
+        todoItems = entry.message.details?.items ?? [];
+      }
     }
   }
 });
@@ -53,4 +64,4 @@ This pattern makes state survive session reloads, forks, and compactions (as lon
 | Use for | State changes, action logs | Information display, command results |
 | LLM sees | The `output` field | The `content` field |
 
-Use `appendEntry` when you are tracking state changes that need to be replayed. Use `sendMessage` when you are displaying a one-time result.
+Use tool result `details` when the state naturally belongs to a tool call and should follow normal conversation branching. Use `appendEntry` for extension-specific state/history that does not fit a normal tool result. Use `sendMessage` when you are displaying a one-time result.

package/src/skills/pi-extension/references/structure.md

@@ -79,12 +79,14 @@ Not every extension needs every directory. A simple extension with one tool migh
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": ">=CURRENT_VERSION",
     "@mariozechner/pi-ai": ">=CURRENT_VERSION",
-    "@mariozechner/pi-tui": ">=CURRENT_VERSION"
+    "@mariozechner/pi-tui": ">=CURRENT_VERSION",
+    "@sinclair/typebox": ">=0.34.0"
   },
   "peerDependenciesMeta": {
     "@mariozechner/pi-coding-agent": { "optional": true },
     "@mariozechner/pi-ai": { "optional": true },
-    "@mariozechner/pi-tui": { "optional": true }
+    "@mariozechner/pi-tui": { "optional": true },
+    "@sinclair/typebox": { "optional": true }
   },
   "devDependencies": {
     "@aliou/biome-plugins": "^0.3.0",
@@ -93,6 +95,7 @@ Not every extension needs every directory. A simple extension with one tool migh
     "@mariozechner/pi-ai": "CURRENT_VERSION",
     "@mariozechner/pi-coding-agent": "CURRENT_VERSION",
     "@mariozechner/pi-tui": "CURRENT_VERSION",
+    "@sinclair/typebox": "0.34.41",
     "@types/node": "^25.0.0",
     "husky": "^9.0.0",
     "typescript": "^5.8.0"
@@ -135,10 +138,10 @@ Only include `pi` sub-fields that are actually used. `skills`, `themes`, `prompt
 
 **`peerDependencies`**: Declares the minimum pi version required. Pi ships these packages and injects them via jiti at runtime, so extensions never need to install them:
 
-- `@mariozechner/pi-coding-agent` — core types, utilities, `Type` (re-exported from TypeBox)
+- `@mariozechner/pi-coding-agent` — core types, utilities, and extension APIs
 - `@mariozechner/pi-tui` — TUI components
 - `@mariozechner/pi-ai` — AI utilities (`StringEnum`, etc.)
-- `@sinclair/typebox` — schema definitions (also re-exported from `pi-coding-agent`)
+- `@sinclair/typebox` — schema definitions for tool parameters and related types
 
 List any of these you import at runtime in `peerDependencies` as optional peers. This prevents npm from installing duplicate copies when a user installs your extension. Use `>=` with the current version when creating.
 

package/src/skills/pi-extension/references/tools.md

@@ -18,7 +18,7 @@ import type {
 } from "@mariozechner/pi-coding-agent";
 import { getMarkdownTheme, keyHint, truncateHead, formatSize } from "@mariozechner/pi-coding-agent";
 import { Container, Markdown, Text } from "@mariozechner/pi-tui";
-import { type Static, Type } from "@mariozechner/pi-coding-agent";
+import { type Static, Type } from "@sinclair/typebox";
 ```
 
 ## Registration
@@ -29,9 +29,9 @@ const myTool = {
   label: "My Tool", // Required: human-readable name for UI
   description: "What this tool does. The LLM reads this to decide when to call it.",
   promptSnippet: "Search for items by query", // One-liner for "Available tools" system prompt
-  promptGuidelines: [ // Guideline bullets for "Guidelines" system prompt when active
-    "Use this tool when the user asks about search",
-    "Prefer specific queries over broad ones",
+  promptGuidelines: [ // Guideline bullets appended verbatim to the global "Guidelines" section when this tool is active
+    "Use my_tool when the user asks about search.",
+    "Prefer specific queries over broad ones when calling my_tool.",
   ],
   parameters: Type.Object({
     query: Type.String({ description: "Search query" }),
@@ -73,7 +73,7 @@ export default function (pi: ExtensionAPI) {
 | `description` | `string` | Yes | What the tool does (LLM reads this) |
 | `parameters` | `TSchema` | Yes | TypeBox schema for arguments |
 | `promptSnippet` | `string` | No | One-liner injected into "Available tools" system prompt. Custom tools without this are omitted from that section. |
-| `promptGuidelines` | `string[]` | No | Guideline bullets appended to "Guidelines" system prompt when this tool is active |
+| `promptGuidelines` | `string[]` | No | Guideline bullets appended verbatim to the global "Guidelines" system prompt section when this tool is active. Write each bullet so it still makes sense standalone. |
 | `execute` | `function` | Yes | Implementation |
 | `renderCall` | `function` | No | Custom call rendering |
 | `renderResult` | `function` | No | Custom result rendering |
@@ -118,6 +118,8 @@ The `onUpdate` parameter can be `undefined`. Calling it without optional chainin
 
 If you override a built-in tool or wrap another tool, audit any delegated `tool.execute(...)` calls during upgrades. These forwarders often pass through `signal`, `onUpdate`, or `ctx` and can silently break when the execute signature changes. Always recheck the delegate call parameter order and include optional parameters that the target tool expects.
 
+Prompt metadata is not inherited automatically when you override a built-in tool. If the original tool had `promptSnippet` or `promptGuidelines` and you still want that system prompt behavior, define those fields explicitly on the override.
+
 ## Return Value
 
 ```typescript
@@ -222,7 +224,7 @@ Both approaches work. Approach 1 is more common in published extensions. Approac
 Use TypeBox (`Type.*`) for parameter schemas. The LLM sees the schema to know what arguments to provide.
 
 ```typescript
-import { Type } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
 
 // Required string
 Type.String({ description: "File path to read" })
@@ -248,6 +250,89 @@ Type.Array(Type.String(), { description: "List of tags" })
 
 Always provide `description` on parameters. The LLM uses these to understand what to pass.
 
+## Prompt Metadata
+
+`promptSnippet` and `promptGuidelines` affect different parts of the default system prompt:
+
+- `promptSnippet` adds a one-line entry to `Available tools`.
+- `promptGuidelines` appends raw bullets to the global `Guidelines` section.
+
+Important implications:
+
+- `promptGuidelines` bullets are not wrapped with the tool name.
+- Write bullets so they still make sense when read out of context.
+- Prefer explicit tool names over phrases like `this tool`.
+
+Good:
+
+```typescript
+promptGuidelines: [
+  "Use my_tool to search project docs before broader web research.",
+  "Prefer specific queries when calling my_tool.",
+]
+```
+
+Weak:
+
+```typescript
+promptGuidelines: [
+  "Use this tool for docs.",
+  "Prefer specific queries.",
+]
+```
+
+Use `promptGuidelines` for short, tool-local rules. If the guidance needs cross-tool sequencing, comparisons against several tools, or dynamic config context, use a `before_agent_start` hook instead.
+
+## Argument Compatibility and Path Handling
+
+Use `prepareArguments(args)` when you need a compatibility shim before schema validation, for example to support an old parameter shape during a migration.
+
+```typescript
+prepareArguments(args) {
+  if (!args || typeof args !== "object") return args;
+  const input = args as { action?: string; oldAction?: string };
+  if (typeof input.oldAction === "string" && input.action === undefined) {
+    return { ...input, action: input.oldAction };
+  }
+  return args;
+}
+```
+
+If your custom tool accepts filesystem paths, normalize a leading `@` before resolving the path. Some models include `@` in path arguments, and the built-in file tools already strip it.
+
+```typescript
+const normalizedPath = params.path.startsWith("@") ? params.path.slice(1) : params.path;
+```
+
+## File-Mutating Tools and Concurrency
+
+Tool calls can run in parallel. If your custom tool mutates files, use `withFileMutationQueue()` so it participates in the same per-file queue as built-in `edit` and `write`.
+
+```typescript
+import { withFileMutationQueue } from "@mariozechner/pi-coding-agent";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+  const normalizedPath = params.path.startsWith("@") ? params.path.slice(1) : params.path;
+  const absolutePath = resolve(ctx.cwd, normalizedPath);
+
+  return withFileMutationQueue(absolutePath, async () => {
+    await mkdir(dirname(absolutePath), { recursive: true });
+    const current = await readFile(absolutePath, "utf8");
+    const next = current.replace(params.oldText, params.newText);
+    await writeFile(absolutePath, next, "utf8");
+
+    return {
+      content: [{ type: "text", text: `Updated ${normalizedPath}` }],
+      details: {},
+    };
+  });
+}
+```
+
+Queue the whole read-modify-write window, not just the final write.
+
 ## Streaming Updates
 
 Use `onUpdate` to stream partial results while the tool executes. This gives the user feedback during long operations.
@@ -753,7 +838,7 @@ import type {
 } from "@mariozechner/pi-coding-agent";
 import { keyHint, formatSize } from "@mariozechner/pi-coding-agent";
 import { Container, Text } from "@mariozechner/pi-tui";
-import { type Static, Type } from "@mariozechner/pi-coding-agent";
+import { type Static, Type } from "@sinclair/typebox";
 
 // Schema
 const parameters = Type.Object({
@@ -780,8 +865,8 @@ const repoTreeTool = {
   description: "List files and directories in a GitHub repository.",
   promptSnippet: "Browse repository file structure",
   promptGuidelines: [
-    "Use this to explore repository structure before reading files",
-    "Start with root path, then drill down into directories",
+    "Use repo_tree to explore repository structure before reading files.",
+    "Start repo_tree at the root path, then drill down into directories.",
   ],
   parameters,