@aliou/pi-dev-kit 0.6.1 → 0.6.3

package/README.md

@@ -1,3 +1,5 @@
+![banner](https://assets.aliou.me/pi-extensions/banners/pi-dev-kit.png)
+
 # Pi Dev Kit
 
 Tools and commands for building, maintaining, and updating Pi extensions.
@@ -57,4 +59,4 @@ Parses the Pi changelog and returns entries for a specific version (or the lates
 
 ## Compatibility
 
-Compatible with Pi 0.50.x and 0.51.0+. Tools that need the extension context use a runtime shim to handle the execute signature difference between versions.
+Compatible with Pi 0.50.x and 0.51.0+. Tools that need the extension context use a runtime shim to handle the execute signature difference between versions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-dev-kit",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "license": "MIT",
   "type": "module",
   "private": false,

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

@@ -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,7 +105,7 @@ 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"`.
@@ -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/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/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"

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,
 

package/src/tools/changelog-tool.ts

@@ -244,9 +244,9 @@ export function setupChangelogTool(pi: ExtensionAPI) {
     promptSnippet: `pi_changelog version="1.2.3" // Get changelog for specific version
 pi_changelog // Get latest changelog`,
     promptGuidelines: [
-      "Use this tool to check what's new in a Pi version",
+      "Use pi_changelog to check what's new in a Pi version",
       "Use pi_changelog_versions first to list available versions",
-      "Leave version empty to get the latest changelog",
+      "Leave version empty for pi_changelog to get the latest changelog",
     ],
 
     parameters: ChangelogParamsSchema,

package/src/tools/docs-tool.ts

@@ -47,8 +47,8 @@ export function setupDocsTool(pi: ExtensionAPI) {
 
     promptSnippet: "List Pi documentation files",
     promptGuidelines: [
-      "Use to discover available Pi documentation",
-      "Returns markdown files from README.md, docs/, and examples/",
+      "Use pi_docs to discover available Pi documentation",
+      "pi_docs returns markdown files from README.md, docs/, and examples/",
     ],
 
     parameters: DocsParamsSchema,

package/src/tools/package-manager-tool.ts

@@ -46,8 +46,8 @@ export function setupPackageManagerTool(pi: ExtensionAPI) {
       "Detect the package manager used in the current project by checking lockfiles and package.json",
     promptSnippet: "Detect the package manager for this project",
     promptGuidelines: [
-      "Use when you need to know which package manager (npm, yarn, pnpm, bun) the project uses",
-      "Helpful before running install commands or scripts",
+      "Use detect_package_manager when you need to know which package manager (npm, yarn, pnpm, bun) the project uses",
+      "detect_package_manager is helpful before running install commands or scripts",
     ],
 
     parameters: Params,

package/src/tools/version-tool.ts

@@ -24,7 +24,7 @@ export function setupVersionTool(pi: ExtensionAPI) {
     description: "Get the version of the currently running Pi instance",
     promptSnippet: "Check the current Pi version.",
     promptGuidelines: [
-      "Use when the user asks about the Pi version or when a task depends on knowing the installed version.",
+      "Use pi_version when the user asks about the Pi version or when a task depends on knowing the installed version.",
     ],
 
     parameters: VersionParams,