@aliou/pi-dev-kit 0.6.4 → 0.7.0

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

@@ -1,274 +1,174 @@
 # Tools
 
-Tools are functions the LLM can call. They are the primary way extensions add capabilities to pi.
+Tools are functions the LLM can call. They are the main way extensions add capabilities to Pi.
 
 ## Imports
 
-Use these imports at the top of your tool file:
+Use the namespace that matches the target Pi package. Examples use the forward namespace.
 
 ```typescript
-import { ToolCallHeader, ToolBody, ToolFooter } from "@aliou/pi-utils-ui";
-import type {
-  AgentToolResult,
-  AgentToolUpdateCallback,
-  ExtensionAPI,
-  ExtensionContext,
-  Theme,
-  ToolRenderResultOptions,
-} 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 "@sinclair/typebox";
+import { ToolBody, ToolCallHeader, ToolFooter } from "@aliou/pi-utils-ui";
+import type { AgentToolResult, ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import {
+  defineTool,
+  formatSize,
+  getMarkdownTheme,
+  keyHint,
+  truncateHead,
+  truncateTail,
+  withFileMutationQueue,
+} from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Container, Markdown, Text } from "@earendil-works/pi-tui";
+import { type Static, Type } from "typebox";
 ```
 
-## Registration
+Use legacy `@mariozechner/*` imports only when the target `@earendil-works/*` package is not available yet.
+
+## Minimal Tool Entry Point
+
+Tool entry points are normal Pi extension entry points. Export a default function and list the file in `package.json` `pi.extensions`.
 
 ```typescript
-const myTool = {
+const parameters = Type.Object({
+  query: Type.String({ description: "Search query" }),
+  limit: Type.Optional(Type.Number({ description: "Max results", default: 10 })),
+});
+
+type MyToolParams = Static<typeof parameters>;
+
+interface MyToolDetails {
+  results: string[];
+}
+
+const myTool = defineTool({
   name: "my_tool",
-  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 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.",
+  label: "My Tool",
+  description: "Search for items by query.",
+  promptSnippet: "Search for items by query",
+  promptGuidelines: [
+    "Use my_tool when the user asks to search these items.",
+    "Prefer specific queries when calling my_tool.",
   ],
-  parameters: Type.Object({
-    query: Type.String({ description: "Search query" }),
-    limit: Type.Optional(Type.Number({ description: "Max results", default: 10 })),
-  }),
-
-  async execute(
-    toolCallId: string,
-    params: MyToolParams,
-    signal: AbortSignal | undefined,
-    onUpdate: AgentToolUpdateCallback<MyToolDetails> | undefined,
-    ctx: ExtensionContext,
-  ): Promise<AgentToolResult<MyToolDetails>> {
-    const results = await doSomething(params.query, params.limit);
+  parameters,
+
+  async execute(_toolCallId, params, signal, onUpdate, ctx): Promise<AgentToolResult<MyToolDetails>> {
+    onUpdate?.({ content: [{ type: "text", text: "Searching..." }] });
+    const results = await searchItems(params.query, { limit: params.limit, signal });
     return {
       content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
       details: { results },
     };
   },
-};
-
-// Typed param alias - define once, use everywhere
-type MyToolParams = Static<typeof myTool.parameters>;
-interface MyToolDetails {
-  results: string[];
-}
+});
 
-export default function (pi: ExtensionAPI) {
+export default function toolsExtension(pi: ExtensionAPI) {
   pi.registerTool(myTool);
 }
 ```
 
-## Tool Definition Fields
+## `defineTool()`
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | `string` | Yes | Snake_case identifier used in tool calls |
-| `label` | `string` | Yes | Human-readable name shown in UI |
-| `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 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 |
+Use `defineTool({...})` for standalone tool objects. It preserves parameter inference from the `parameters` field when the tool is stored in a variable or passed through arrays.
 
-## Typed Param Alias
+Rules:
 
-Define a type alias at the top of your file instead of repeating `Static<typeof parameters>`:
+- Do not pass explicit generic arguments to `defineTool`.
+- Do not annotate callback parameters unless TypeScript needs help.
+- Add a `Static<typeof parameters>` alias for helper functions and action modules.
+- If you want `renderResult` to know the `details` shape, annotate `execute` with `Promise<AgentToolResult<MyDetails>>`.
 
-```typescript
-const parameters = Type.Object({
-  query: Type.String({ description: "Search query" }),
-  limit: Type.Optional(Type.Number({ description: "Max results", default: 10 })),
-});
+## Tool Definition Fields
 
-type MyToolParams = Static<typeof parameters>;
-// Use MyToolParams everywhere: execute params, renderCall args, context.args, etc.
-```
+| Field | Required | Notes |
+|---|---:|---|
+| `name` | Yes | Snake_case identifier used in tool calls. |
+| `label` | Yes | Human-readable display name. |
+| `description` | Yes | Model-facing description. |
+| `parameters` | Yes | TypeBox 1.x schema from `typebox`. |
+| `execute` | Yes | `(toolCallId, params, signal, onUpdate, ctx)`. |
+| `promptSnippet` | No | One-line entry in Available tools. Custom tools are omitted there when absent. |
+| `promptGuidelines` | No | Raw bullets appended to the global Guidelines section. Each bullet must name the tool. |
+| `prepareArguments` | No | Compatibility shim before schema validation. |
+| `executionMode` | No | Use `"sequential"` for shared-state tools that cannot run concurrently. |
+| `renderCall` / `renderResult` | No | Custom TUI component renderers. |
+| `renderShell` | No | Use `"self"` only when the default boxed shell gets in the way. |
 
 ## Execute Signature
 
 ```typescript
-execute(
-  toolCallId: string,
-  params: Static<TParams>,      // Typed from the parameters schema
-  signal: AbortSignal | undefined,
-  onUpdate: AgentToolUpdateCallback<TDetails> | undefined,
-  ctx: ExtensionContext,
-): Promise<AgentToolResult<TDetails>>
+async execute(toolCallId, params, signal, onUpdate, ctx): Promise<AgentToolResult<TDetails>>
 ```
 
-**Parameter order matters.** The signal comes before onUpdate.
+Parameter order matters. `signal` comes before `onUpdate`.
 
-Always use optional chaining when calling `onUpdate`:
+Use optional chaining for updates:
 
 ```typescript
-onUpdate?.({ output: "partial result", details: { progress: 50 } });
+onUpdate?.({
+  content: [{ type: "text", text: "Working..." }],
+  details: { progress: 50 },
+});
 ```
 
-The `onUpdate` parameter can be `undefined`. Calling it without optional chaining will throw.
-
-## Tool Overrides and Delegation
-
-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
+Forward `signal` to all abort-aware work:
 
 ```typescript
-return {
-  content: (TextContent | ImageContent)[],  // Content blocks sent to the LLM
-  details?: TDetails,                       // Arbitrary data available in the renderer
-};
+const response = await fetch(url, { signal });
+const result = await pi.exec("git", ["status", "--porcelain"], { signal, cwd: ctx.cwd });
 ```
 
-- `content` is what the LLM sees. Each block is `{ type: "text", text: "..." }` or an image. Keep it structured and concise.
-- `details` is what the renderer sees. Put rich data here for custom display.
+Do not use Node `child_process` for normal commands. Use `pi.exec(command, args, options)` so Pi handles CWD, cancellation, output capture, and lifecycle integration.
 
-Common pattern:
+## Return Value and Errors
 
 ```typescript
 return {
-  content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
-  details: { results },
+  content: [{ type: "text", text: "Text sent to the LLM" }],
+  details: { rich: "data for rendering and state" },
+  terminate: true, // optional final/structured-output tools only
 };
 ```
 
-## Error Handling
-
-To report a tool call failure, **throw an error**. The framework catches it and produces a result with `isError: true` on the context.
-
-```typescript
-execute: async (toolCallId, params, signal, onUpdate, ctx) => {
-  const result = await fetchData(params.query);
-  if (!result) {
-    throw new Error("No results found. Try a different query.");
-  }
-  return {
-    content: [{ type: "text", text: JSON.stringify(result) }],
-    details: { result },
-  };
-},
-```
-
-The framework's `createErrorToolResult` sets `details: {}` (empty object, not `undefined`) and puts the error message in `content`:
-
-```typescript
-// Framework produces when tool throws:
-{
-  content: [{ type: "text", text: errorMessage }],
-  details: {}
-}
-// And sets context.isError = true in renderResult
-```
-
-### Error rendering in `renderResult`
-
-The framework passes `isError` on the 4th `context` parameter to `renderResult`, but `ToolRenderContext` is not currently exported from the public API. Two practical approaches:
-
-**Approach 1: Check for missing expected fields in `details`** (recommended for extensions)
-
-When a tool throws, the framework sets `details: {}` (empty object). Check for missing expected fields:
-
-```typescript
-renderResult(
-  result: AgentToolResult<MyToolDetails>,
-  options: ToolRenderResultOptions,
-  theme: Theme,
-) {
-  const { details } = result;
-
-  // details is {} when tool threw — expected fields are missing
-  if (!details?.results) {
-    const textBlock = result.content.find((c) => c.type === "text");
-    const errorMsg = (textBlock?.type === "text" && textBlock.text) || "Operation failed";
-    return new Text(theme.fg("error", errorMsg), 0, 0);
-  }
-  // ... normal rendering
-}
-```
-
-**Approach 2: Use the 4th context parameter** (used by native tools)
+- `content` is sent to the LLM. Keep it concise and useful.
+- `details` is persisted in the session and used by renderers. Put state snapshots here when the tool mutates extension state.
+- `terminate: true` skips the automatic follow-up LLM call only when every finalized tool in the current batch also terminates.
+- Throw an error to mark a tool result as failed. Returning an object never sets `isError`.
 
-Define a minimal interface locally:
+When a tool throws, Pi creates an error result with `details: {}` and the error message in `content`. Renderers should check for missing expected fields or use the 4th render context's `isError` field.
 
-```typescript
-interface RenderContext { isError: boolean }
-
-renderResult(
-  result: AgentToolResult<MyToolDetails>,
-  options: ToolRenderResultOptions,
-  theme: Theme,
-  context: RenderContext,
-) {
-  if (context.isError) {
-    const textBlock = result.content.find((c) => c.type === "text");
-    const errorMsg = textBlock?.type === "text" ? textBlock.text : "Operation failed";
-    return new Text(theme.fg("error", errorMsg), 0, 0);
-  }
-  // ... normal rendering
-}
-```
+## Parameters
 
-Both approaches work. Approach 1 is more common in published extensions. Approach 2 is what native tools use.
-
-## Parameters Schema
-
-Use TypeBox (`Type.*`) for parameter schemas. The LLM sees the schema to know what arguments to provide.
+Use TypeBox 1.x from `typebox`. Always add useful descriptions.
 
 ```typescript
-import { Type } from "@sinclair/typebox";
-
-// Required string
-Type.String({ description: "File path to read" })
-
-// Optional with default
-Type.Optional(Type.Number({ description: "Max results", default: 10 }))
-
-// Enum (string union)
-Type.StringEnum(["created", "updated", "relevance"], { description: "Sort order" })
-
-// Boolean
-Type.Boolean({ description: "Include hidden files" })
-
-// Nested object
-Type.Object({
-  name: Type.String(),
-  value: Type.String(),
-})
-
-// Array
-Type.Array(Type.String(), { description: "List of tags" })
+const parameters = Type.Object({
+  path: Type.String({ description: "File path" }),
+  includeHidden: Type.Optional(Type.Boolean({ description: "Include hidden files", default: false })),
+  sort: Type.Optional(StringEnum(["created", "updated", "relevance"] as const, {
+    description: "Sort order",
+  })),
+  tags: Type.Optional(Type.Array(Type.String({ description: "Tag" }))),
+});
 ```
 
-Always provide `description` on parameters. The LLM uses these to understand what to pass.
+Use `StringEnum` from `pi-ai` for model-facing string enums. Avoid `Type.Union([Type.Literal(...)])`; it is not compatible with all providers.
 
 ## 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.
+`promptSnippet` and `promptGuidelines` affect different system prompt sections:
 
-Important implications:
+- `promptSnippet` adds one line under Available tools.
+- `promptGuidelines` appends raw bullets to the global Guidelines section when the tool is active.
 
-- `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`.
+Because `promptGuidelines` are not grouped under the tool, each bullet must name the exact tool.
 
 Good:
 
 ```typescript
 promptGuidelines: [
-  "Use my_tool to search project docs before broader web research.",
-  "Prefer specific queries when calling my_tool.",
+  "Use repo_tree to inspect repository structure before reading individual files.",
+  "Start repo_tree at the root path, then drill into directories as needed.",
 ]
 ```
 
@@ -276,16 +176,16 @@ Weak:
 
 ```typescript
 promptGuidelines: [
-  "Use this tool for docs.",
-  "Prefer specific queries.",
+  "Use this tool before reading files.",
+  "Start at the root path.",
 ]
 ```
 
-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.
+Use per-tool metadata for simple guidance. Use a `before_agent_start` hook for dynamic config, cross-tool workflows, or complex orchestration.
 
-## Argument Compatibility and Path Handling
+## Argument Compatibility
 
-Use `prepareArguments(args)` when you need a compatibility shim before schema validation, for example to support an old parameter shape during a migration.
+Use `prepareArguments(args)` for backward-compatible migrations of old session tool-call shapes. It runs before validation. Keep the public schema strict.
 
 ```typescript
 prepareArguments(args) {
@@ -298,21 +198,18 @@ prepareArguments(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.
+## Paths and File Mutation
+
+If a tool accepts file paths, strip a leading `@` before resolving. Built-in tools do this because models sometimes include `@` from path mentions.
 
 ```typescript
 const normalizedPath = params.path.startsWith("@") ? params.path.slice(1) : params.path;
+const absolutePath = resolve(ctx.cwd, normalizedPath);
 ```
 
-## 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`.
+If a custom tool mutates files, wrap the whole read-modify-write window in `withFileMutationQueue()` so sibling parallel tool calls cannot overwrite each other.
 
 ```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);
@@ -322,120 +219,94 @@ async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
     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: {},
+      details: { path: normalizedPath },
     };
   });
 }
 ```
 
-Queue the whole read-modify-write window, not just the final write.
+## Concurrency
 
-## Streaming Updates
-
-Use `onUpdate` to stream partial results while the tool executes. This gives the user feedback during long operations.
+Pi runs sibling tool calls in parallel by default. Add `executionMode: "sequential"` when this tool must serialize with sibling tool calls, for example when it mutates shared in-memory state, drives a cursor/game, or depends on strict call order.
 
 ```typescript
-execute: async (toolCallId, params, signal, onUpdate, ctx) => {
-  for (const chunk of chunks) {
-    const partial = processChunk(chunk);
-    onUpdate?.({
-      content: [{ type: "text", text: partial }],
-      details: { progress: chunk.index / chunks.length },
-    });
-  }
-  return {
-    content: [{ type: "text", text: finalResult }],
-    details: { complete: true },
-  };
-},
+const statefulTool = defineTool({
+  name: "game_move",
+  label: "Game Move",
+  description: "Apply a move to the current game state.",
+  executionMode: "sequential",
+  parameters,
+  async execute(_toolCallId, params) {
+    // Mutates shared in-memory state safely.
+  },
+});
 ```
 
-## Custom Rendering
+Prefer making core operations concurrency-safe. Use sequential mode only when call order is inherently meaningful.
 
-Override how a tool's invocation and result appear in the TUI.
+## Rendering
 
-### `renderCall` Signature
+Custom renderers return TUI `Component` objects.
 
-```typescript
-renderCall(args: MyToolParams, theme: Theme): Component
-```
-
-A 3rd `context` param is available from the framework but rarely needed in `renderCall`.
+### `renderCall`
 
-Use `ToolCallHeader` from `@aliou/pi-utils-ui`:
+Use `ToolCallHeader` for a stable, scannable call line.
 
 ```typescript
-renderCall(args: MyToolParams, theme: Theme) {
+renderCall(args, theme) {
   return new ToolCallHeader(
     {
-      toolName: "My Tool",
-      action: "search",           // Optional: for multi-action tools
-      mainArg: `"${args.query}"`, // Primary thing user scans for
-      optionArgs: [`limit=${args.limit ?? 10}`], // Compact key-value pairs
-      longArgs: [],               // Long text goes here
-      showColon: true,            // Whether to show colon after tool name
+      toolName: "Repo Tree",
+      action: args.action,
+      mainArg: `${args.owner}/${args.repo}`,
+      optionArgs: args.path ? [{ label: "path", value: args.path }] : [],
+      longArgs: args.instructions ? [{ label: "instructions", value: args.instructions }] : [],
     },
     theme,
   );
 }
 ```
 
-### `renderResult` Signature
+Header extraction order:
 
-```typescript
-renderResult(
-  result: AgentToolResult<TDetails>,
-  options: ToolRenderResultOptions,
-  theme: Theme,
-): Component
-```
+1. Action for multi-action tools.
+2. One main argument users scan for first.
+3. Short option args.
+4. Long args on follow-up lines.
+
+### `renderResult`
 
-- `options` has `expanded` and `isPartial`
-- `result.details` is `{}` (empty object) when the tool threw an error
-- A 4th `context` param is available (see Error Handling above) but not required
+Handle partial state first, then errors, then normal output.
 
 ```typescript
-renderResult(
-  result: AgentToolResult<MyToolDetails>,
-  options: ToolRenderResultOptions,
-  theme: Theme,
-) {
-  // 1. Handle partial state first with stable message
+renderResult(result, options, theme) {
   if (options.isPartial) {
-    return new Text(theme.fg("muted", "MyTool: fetching..."), 0, 0);
+    return new Text(theme.fg("muted", "Repo Tree: fetching..."), 0, 0);
   }
 
   const { details } = result;
-
-  // 2. Handle errors: details is {} when tool threw
-  if (!details?.results) {
+  if (!details?.entries) {
     const textBlock = result.content.find((c) => c.type === "text");
-    const errorMsg = (textBlock?.type === "text" && textBlock.text) || "Operation failed";
-    return new Text(theme.fg("error", errorMsg), 0, 0);
+    const message = textBlock?.type === "text" ? textBlock.text : "Repo Tree failed";
+    return new Text(theme.fg("error", message), 0, 0);
   }
 
-  // 3. Build fields for ToolBody (showCollapsed controls collapsed/expanded visibility)
-  const items = details.results;
-
-  const fields: Array<{ label: string; value: string; showCollapsed?: boolean } | Text> = [
-    { label: "Results", value: `${items.length} items`, showCollapsed: true },
+  const fields = [
+    { label: "Location", value: `${details.owner}/${details.repo}`, showCollapsed: true },
+    { label: "Entries", value: `${details.entries.length}`, showCollapsed: true },
   ];
 
-  // 4. Build conditional footer
-  const footerItems: Array<{ label: string; value: string }> = [];
-  if (items.length > 0) {
-    footerItems.push({ label: "count", value: `${items.length}` });
+  const footerItems = [];
+  if (!options.expanded && details.entries.length > 5) {
+    footerItems.push({ value: keyHint("app.tools.expand", "to expand") });
   }
 
   return new ToolBody(
     {
       fields,
-      footer: footerItems.length > 0
-        ? new ToolFooter(theme, { items: footerItems, separator: " | " })
-        : undefined,
+      footer: footerItems.length > 0 ? new ToolFooter(theme, { items: footerItems }) : undefined,
       includeSpacerBeforeFooter: fields.length > 0,
     },
     options,
@@ -444,590 +315,115 @@ renderResult(
 }
 ```
 
-### `renderCall` Design Guide
-
-The `process` extension is a good baseline. Its call renderer is deterministic and keeps headers readable.
-
-Use this extraction order when building header parts:
-
-1. **Action first**: always show action for multi-action tools (`start`, `list`, `kill`, ...).
-2. **Pick one main arg**: choose the single value the user scans for first (name, id, or short command).
-3. **Promote short fields to options**: compact values become option args (`end=true`, `limit=10`).
-4. **Demote long fields to long args**: commands/prompts/instructions move to labeled follow-up lines.
-5. **Keep it stable**: same inputs should produce same ordering and formatting.
-
-Implementation pattern:
-- Build `mainArg`, `optionArgs`, `longArgs` first, then pass to `ToolCallHeader`.
-- Quote user-provided names (`"backend"`) when that improves visual parsing.
-- Cap inline length (e.g. 60-80 chars), then spill to `longArgs`.
-
-### `renderResult` Guidelines
-
-- Handle `isPartial` first with a **stable, tool-scoped message** like `"MyTool: fetching..."`. Do NOT echo streaming content.
-- Handle errors by checking for missing expected fields in `details` (framework sets `details: {}` on throw). Alternatively use the 4th `context` param with `context.isError`.
-- Use `ToolBody` with `showCollapsed: true` fields for collapsed/expanded filtering.
-- Use `ToolFooter` for stats/metadata. Omit when empty: `footer: items.length > 0 ? new ToolFooter(...) : undefined`.
-- Use `includeSpacerBeforeFooter: fields.length > 0` to avoid blank line when body is empty.
-- Remove redundant success footer items — don't show `status: ok` when success is obvious.
-- Use `Container` + `addChild()` for multi-element results instead of string concatenation.
-- Use `Markdown` component for rich markdown content:
-  ```typescript
-  new Markdown(text, 0, 0, getMarkdownTheme(), { color: (t) => theme.fg("toolOutput", t) })
-  ```
-- Use `keyHint("app.tools.expand", "to expand")` for expand hints.
-- Collapsed result should show **actionable preview** (last N lines, first N items with status), not just a status badge.
-- Humanize error messages with names first: `"Could not get X for "name" (id)"`.
-
-## Tool UI Rendering Guidelines
-
-When customizing tool rendering, keep call/result UI predictable and scannable.
-
-### `renderCall` format
-
-Use this line model:
-
-- First line: `[Tool Name]: [Action] [Main arg] [Option args]`
-- Additional lines: long args only
-
 Guidelines:
-- Tool name should be a human display label (`label`), not a raw internal identifier (`name`).
-- Show `action` only when it adds meaning (multi-action tools like process managers).
-- Main arg should be the primary thing user cares about (query, session id, target id/name).
-- Option args should be compact key-value pairs (`limit=10`, `cwd=/path`).
-- Long text (prompt/task/question/context/instructions) goes to additional lines.
-- Prefer wrapping to preserve full meaning over aggressive truncation.
-- For tools without actions, omit colon suffix after tool name if that reads better in your UI system.
-
-### `renderResult` layout
-
-- Handle `isPartial` first. Return a short stable loading state with tool-scoped message.
-- Keep the first non-loading line as a status summary (`Found N results`, `Updated 3 files`, `Failed: reason`).
-- Use `expanded` to switch between compact and full output. Compact should show the top few items plus an omission hint.
-- Keep body content focused on state + key output; avoid dumping raw JSON unless it is the actual output.
-- If you render a footer (stats, backend, counts), use `includeSpacerBeforeFooter` to control blank line.
-- Keep footer concise and stable across states.
-- Return `undefined` when custom rendering adds no value; fallback rendering is better than noisy UI.
-
-## Tool Call + UI Consistency Contract
-
-Use this contract to keep tool UX consistent across extensions:
-
-1. **Call line is for scanability**: `renderCall` first line follows `[Tool Name]: [Action] [Main arg] [Option args]`.
-2. **Result detects errors** by checking for missing expected fields in `details` (framework sets `details: {}` on throw).
-3. **Long text moves down**: prompts, instructions, and context go to follow-up lines, not the call header.
-4. **Partial updates use a fixed tool-scoped string**, not echoed streaming content.
-5. **Expanded controls density**: compact view shows summary + subset; expanded view shows full detail.
-6. **No mode leaks in tool renderers**: `renderCall`/`renderResult` should not branch on mode. Mode-specific behavior belongs in command/tool logic (`references/modes.md`).
-
-Related references:
-- `references/modes.md` for `custom()` fallback behavior and RPC/Print handling.
-- `references/components.md` for interactive component authoring.
-- `references/messages.md` for persistent display via `sendMessage` + `registerMessageRenderer`.
-
-## Naming Conventions
 
-For extensions wrapping a third-party API, prefix tool names with the API name to avoid conflicts:
-
-```
-linkup_web_search
-linkup_web_fetch
-synthetic_web_search
-```
-
-For internal/custom tools, no prefix is needed:
-
-```
-get_current_time
-processes
-```
-
-Use snake_case for all tool names.
-
-## Abort Signal
-
-The `signal` parameter lets you cancel long-running operations when the user interrupts (e.g. pressing Escape). If the tool does not forward the signal, the underlying operation keeps running even after the user cancels, wasting resources and API credits.
-
-```typescript
-execute: async (toolCallId, params, signal, onUpdate, ctx) => {
-  const response = await fetch(url, { signal });
-  // If the user cancels, fetch throws an AbortError
-  return { content: [{ type: "text", text: await response.text() }], details: {} };
-},
-```
-
-Pass `signal` to every async operation that supports it: `fetch()` calls, `pi.exec()` calls, SDK clients, etc.
-
-When wrapping an API client, thread the signal through the entire call chain. The client methods should accept an optional `signal` and forward it to the underlying `fetch()`:
-
-```typescript
-// In the tool:
-async execute(_toolCallId, params, signal, onUpdate, ctx) {
-  const result = await client.search({ query: params.query, signal });
-  // ...
-}
-
-// In the client:
-async search(params: { query: string; signal?: AbortSignal }) {
-  return this.request("/search", { method: "POST", body: ... }, params.signal);
-}
-
-private async request<T>(endpoint: string, options: RequestInit = {}, signal?: AbortSignal) {
-  return fetch(`${BASE_URL}${endpoint}`, { ...options, signal, headers: { ... } });
-}
-```
-
-Do not prefix signal with underscore (`_signal`) unless the tool genuinely cannot use it. A dangling `_signal` is a sign of a missing cancellation path.
+- Partial output uses a fixed tool-scoped message; do not echo streaming content.
+- Collapsed view should show useful preview, not just `ok`.
+- Expanded view can add full details.
+- Omit empty footers.
+- Use `Markdown` with `getMarkdownTheme()` for rich markdown.
+- Use `context.lastComponent` only when reusing a component instance buys real performance.
+- Set `renderShell: "self"` only when the default boxed shell prevents the desired layout.
 
 ## Output Truncation
 
-For tools that may return large outputs, use `truncateHead()` which returns a `TruncationResult`:
+Tools must avoid overwhelming model context. Use `truncateHead` for content where the beginning matters and `truncateTail` for logs or command output where the end matters.
 
 ```typescript
-import { truncateHead, formatSize } from "@mariozechner/pi-coding-agent";
-import { createWriteStream } from "fs";
-import { tmpdir } from "os";
-import { join } from "path";
-
 interface FetchDetails {
-  content: string;
   url: string;
+  content: string;
   truncated: boolean;
   totalLines: number;
-  totalBytes: number;
   outputLines: number;
+  totalBytes: number;
   outputBytes: number;
   tempFile?: string;
 }
 
-async execute(
-  _toolCallId: string,
-  params: FetchParams,
-  signal: AbortSignal | undefined,
-  _onUpdate: undefined,
-  _ctx: ExtensionContext,
-): Promise<AgentToolResult<FetchDetails>> {
+async execute(_toolCallId, params, signal): Promise<AgentToolResult<FetchDetails>> {
   const response = await fetch(params.url, { signal });
   const fullContent = await response.text();
-
-  // truncateHead keeps the tail (most recent content)
-  const truncated = truncateHead(fullContent, {
-    maxBytes: 50000,
-    maxLines: 2000,
-  });
+  const truncated = truncateHead(fullContent, { maxBytes: 50_000, maxLines: 2_000 });
 
   const details: FetchDetails = {
-    content: truncated.content,
     url: params.url,
+    content: truncated.content,
     truncated: truncated.truncated,
     totalLines: truncated.totalLines,
-    totalBytes: truncated.totalBytes,
     outputLines: truncated.outputLines,
+    totalBytes: truncated.totalBytes,
     outputBytes: truncated.outputBytes,
   };
 
-  // Write full content to temp file if truncated
+  let text = truncated.content;
   if (truncated.truncated) {
-    const tempFile = join(tmpdir(), `web-fetch-${Date.now()}.txt`);
-    const stream = createWriteStream(tempFile);
-    stream.write(fullContent);
-    stream.end();
-    details.tempFile = tempFile;
+    details.tempFile = await writeTempFile(fullContent);
+    text += `\n\n[Output truncated: ${truncated.outputLines}/${truncated.totalLines} lines, `;
+    text += `${formatSize(truncated.outputBytes)}/${formatSize(truncated.totalBytes)}. `;
+    text += `Full output: ${details.tempFile}]`;
   }
 
-  return {
-    content: [{ type: "text", text: truncated.content }],
-    details,
-  };
+  return { content: [{ type: "text", text }], details };
 }
 ```
 
-### Truncation Result Fields
-
-```typescript
-interface TruncationResult {
-  content: string;      // The truncated content (or full if not truncated)
-  truncated: boolean;   // Whether truncation occurred
-  totalLines: number;   // Original total lines
-  totalBytes: number;   // Original total bytes
-  outputLines: number;  // Lines in output
-  outputBytes: number;  // Bytes in output
-}
-```
-
-### Rendering Truncated Output
-
-```typescript
-renderResult(
-  result: AgentToolResult<FetchDetails>,
-  options: ToolRenderResultOptions,
-  theme: Theme,
-) {
-  if (options.isPartial) {
-    return new Text(theme.fg("muted", "WebFetch: fetching..."), 0, 0);
-  }
-
-  const { details } = result;
-
-  if (!details?.content) {
-    const textBlock = result.content.find((c) => c.type === "text");
-    const errorMsg = (textBlock?.type === "text" && textBlock.text) || "Fetch failed";
-    return new Text(theme.fg("error", errorMsg), 0, 0);
-  }
-  const container = new Container();
-
-  // Body with content preview
-  const fields = [
-    { label: "URL", value: details.url, showCollapsed: true },
-    { label: "Size", value: formatSize(details.totalBytes), showCollapsed: true },
-  ];
-
-  container.addChild(new ToolBody(theme, { fields, expanded: options.expanded }));
-
-  // Footer with truncation info
-  const footerItems = [];
-
-  if (details.truncated) {
-    footerItems.push(
-      { label: "showing", value: `${details.outputLines}/${details.totalLines} lines` },
-      { label: "full output", value: details.tempFile ?? "temp file" },
-    );
-  } else {
-    footerItems.push({ label: "lines", value: `${details.totalLines}` });
-  }
-
-  container.addChild(
-    new ToolFooter(theme, {
-      items: footerItems,
-      separator: " | ",
-      includeSpacerBeforeFooter: fields.length > 0,
-    }),
-  );
-
-  return container;
-}
-```
+Always tell the LLM when output was truncated and where full output was saved.
 
 ## Multi-Action Tools
 
-For tools with multiple actions (e.g., `start`, `list`, `kill`), organize code for maintainability:
-
-### File Structure
+Use a directory when one tool has several actions.
 
 ```
-tools/
-  my_tool/
-    index.ts           // Tool definition, registration, execute switch
-    actions/
-      start.ts         // start action implementation
-      list.ts          // list action implementation
-      kill.ts          // kill action implementation
-    render.ts          // renderCall and renderResult (when complex)
-    types.ts           // Shared types and param schema
+tools/my_tool/
+  index.ts
+  actions/start.ts
+  actions/list.ts
+  actions/kill.ts
+  render.ts
+  types.ts
 ```
 
-### Action Pattern
+Pattern:
 
-Each action takes an SDK client and typed params, returns typed results:
-
-```typescript
-// actions/start.ts
-export interface StartParams {
-  name: string;
-  command: string;
-  cwd?: string;
-}
-
-export interface StartResult {
-  sessionId: string;
-  pid: number;
-}
-
-export async function start(
-  client: MyClient,
-  params: StartParams,
-  signal?: AbortSignal,
-): Promise<StartResult> {
-  return client.startSession({
-    name: params.name,
-    command: params.command,
-    cwd: params.cwd,
-    signal,
-  });
-}
-```
+- `types.ts`: parameter schema, `Static` alias, details/result types.
+- `actions/*`: Pi-free or mostly Pi-free action logic.
+- `render.ts`: `renderCall`/`renderResult` when complex.
+- `index.ts`: `defineTool`, execute switch, registration.
 
-### Execute Delegation
+Inside the `defineTool` execute callback, inference is enough. If action functions need typed inputs, use the alias from `types.ts`.
 
 ```typescript
-// index.ts
-async execute(
-  toolCallId: string,
-  params: MyToolParams,
-  signal: AbortSignal | undefined,
-  onUpdate: AgentToolUpdateCallback<MyToolDetails> | undefined,
-  ctx: ExtensionContext,
-): Promise<AgentToolResult<MyToolDetails>> {
+async execute(_toolCallId, params, signal, onUpdate, ctx): Promise<AgentToolResult<MyToolDetails>> {
   switch (params.action) {
     case "start":
       return startAction(client, params, signal, onUpdate, ctx);
     case "list":
       return listAction(client, params, signal);
-    case "kill":
-      return killAction(client, params, signal);
     default:
       throw new Error(`Unknown action: ${params.action}`);
   }
 }
 ```
 
-### Separate Render Module
-
-When rendering is complex, extract to `render.ts`:
-
-```typescript
-// render.ts
-export function renderCall(args: MyToolParams, theme: Theme) {
-  return new ToolCallHeader(
-    {
-      toolName: "MyTool",
-      action: args.action,
-      mainArg: getMainArg(args),
-      optionArgs: getOptionArgs(args),
-      longArgs: getLongArgs(args),
-    },
-    theme,
-  );
-}
-
-export function renderResult(
-  result: AgentToolResult<MyToolDetails>,
-  options: ToolRenderResultOptions,
-  theme: Theme,
-) {
-  // Complex rendering logic here
-}
-```
-
-```typescript
-// index.ts
-import { renderCall, renderResult } from "./render.js";
-
-const myTool = {
-  // ...
-  renderCall,
-  renderResult,
-};
-```
+## Naming
 
-**Examples to reference:**
-- `pi-processes`: Multi-action process management with complex rendering
-- `pi-linear`: Multi-action Linear API integration
+- Use snake_case tool names.
+- Prefix third-party integrations with the API/product name (`linkup_web_search`, `linear_issue`).
+- Internal tools can use direct names (`get_current_time`, `process`).
+- Display names in UI should use `label`, not raw tool IDs.
 
-## Full Example
+## Checklist
 
-Here's a realistic tool demonstrating all the patterns:
-
-```typescript
-import { ToolCallHeader, ToolBody, ToolFooter } from "@aliou/pi-utils-ui";
-import type {
-  AgentToolResult,
-  ExtensionAPI,
-  ExtensionContext,
-  Theme,
-  ToolRenderResultOptions,
-} 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 "@sinclair/typebox";
-
-// Schema
-const parameters = Type.Object({
-  owner: Type.String({ description: "Repository owner" }),
-  repo: Type.String({ description: "Repository name" }),
-  path: Type.Optional(Type.String({ description: "File or directory path", default: "" })),
-});
-
-// Typed aliases
-type RepoTreeParams = Static<typeof parameters>;
-
-interface RepoTreeDetails {
-  owner: string;
-  repo: string;
-  path: string;
-  entries: Array<{ name: string; type: "file" | "dir"; size?: number }>;
-  truncated: boolean;
-}
-
-// Tool definition
-const repoTreeTool = {
-  name: "repo_tree",
-  label: "Repo Tree",
-  description: "List files and directories in a GitHub repository.",
-  promptSnippet: "Browse repository file structure",
-  promptGuidelines: [
-    "Use repo_tree to explore repository structure before reading files.",
-    "Start repo_tree at the root path, then drill down into directories.",
-  ],
-  parameters,
-
-  async execute(
-    _toolCallId: string,
-    params: RepoTreeParams,
-    signal: AbortSignal | undefined,
-    _onUpdate: undefined,
-    _ctx: ExtensionContext,
-  ): Promise<AgentToolResult<RepoTreeDetails>> {
-    const response = await fetch(
-      `https://api.github.com/repos/${params.owner}/${params.repo}/contents/${params.path ?? ""}`,
-      { signal, headers: { Accept: "application/vnd.github.v3+json" } },
-    );
-
-    if (!response.ok) {
-      if (response.status === 404) {
-        throw new Error(
-          `Could not find repository "${params.owner}/${params.repo}" or path "${params.path ?? ""}"`,
-        );
-      }
-      throw new Error(`GitHub API error: ${response.status} ${response.statusText}`);
-    }
-
-    const data = await response.json();
-
-    // GitHub returns a single object for files, array for directories
-    const entries = Array.isArray(data) ? data : [data];
-
-    const processed = entries.map((entry: any) => ({
-      name: entry.name,
-      type: entry.type === "dir" ? "dir" as const : "file" as const,
-      size: entry.size,
-    }));
-
-    // Sort: directories first, then files, alphabetically within each
-    processed.sort((a, b) => {
-      if (a.type !== b.type) return a.type === "dir" ? -1 : 1;
-      return a.name.localeCompare(b.name);
-    });
-
-    const truncated = processed.length > 100;
-
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(truncated ? processed.slice(0, 100) : processed, null, 2),
-        },
-      ],
-      details: {
-        owner: params.owner,
-        repo: params.repo,
-        path: params.path ?? "",
-        entries: processed,
-        truncated,
-      },
-    };
-  },
-
-  renderCall(args: RepoTreeParams, theme: Theme) {
-    return new ToolCallHeader(
-      {
-        toolName: "Repo Tree",
-        mainArg: `${args.owner}/${args.repo}`,
-        optionArgs: args.path ? [`path=${args.path}`] : [],
-        longArgs: [],
-      },
-      theme,
-    );
-  },
-
-  renderResult(
-    result: AgentToolResult<RepoTreeDetails>,
-    options: ToolRenderResultOptions,
-    theme: Theme,
-  ) {
-    // 1. Stable partial message
-    if (options.isPartial) {
-      return new Text(theme.fg("muted", "RepoTree: fetching..."), 0, 0);
-    }
-
-    const { details } = result;
-
-    // 2. Error handling: details is {} when tool threw
-    if (!details?.entries) {
-      const textBlock = result.content.find((c) => c.type === "text");
-      const errorMsg = (textBlock?.type === "text" && textBlock.text) || "Failed to list repository";
-      return new Text(theme.fg("error", errorMsg), 0, 0);
-    }
-    const container = new Container();
-    const entries = details?.entries ?? [];
-    const dirs = entries.filter((e) => e.type === "dir");
-    const files = entries.filter((e) => e.type === "file");
-
-    // 3. Body fields with showCollapsed for collapsed/expanded control
-    const fields: Array<{ label: string; value: string; showCollapsed: boolean }> = [
-      {
-        label: "Location",
-        value: `${details.owner}/${details.repo}${details.path ? `/${details.path}` : ""}`,
-        showCollapsed: true,
-      },
-      {
-        label: "Contents",
-        value: `${dirs.length} dirs, ${files.length} files`,
-        showCollapsed: true,
-      },
-    ];
-
-    container.addChild(new ToolBody(theme, { fields, expanded: options.expanded }));
-
-    // 4. Entry list (in expanded view)
-    if (options.expanded && entries.length > 0) {
-      const entryLines = entries
-        .slice(0, 50)
-        .map((e) => {
-          const icon = e.type === "dir" ? "📁" : "📄";
-          const size = e.size !== undefined ? ` (${formatSize(e.size)})` : "";
-          return `${icon} ${e.name}${size}`;
-        })
-        .join("\n");
-
-      container.addChild(new Text(entryLines, 0, 0));
-
-      if (entries.length > 50) {
-        container.addChild(
-          new Text(theme.fg("muted", `... and ${entries.length - 50} more`), 0, 0),
-        );
-      }
-    }
-
-    // 5. Conditional footer
-    const footerItems = [];
-
-    if (details?.truncated) {
-      footerItems.push({ label: "showing", value: "first 100 entries" });
-    }
-
-    if (entries.length > 0) {
-      footerItems.push({ label: "total", value: `${entries.length} items` });
-    }
-
-    if (!options.expanded && entries.length > 5) {
-      footerItems.push({ label: "", value: keyHint("app.tools.expand", "to expand") });
-    }
-
-    if (footerItems.length > 0) {
-      container.addChild(
-        new ToolFooter(theme, {
-          items: footerItems,
-          separator: " | ",
-          includeSpacerBeforeFooter: fields.length > 0,
-        }),
-      );
-    }
-
-    return container;
-  },
-};
-
-export default function (pi: ExtensionAPI) {
-  pi.registerTool(repoTreeTool);
-}
-```
+- [ ] Tool uses `defineTool({...})` with no explicit generic args.
+- [ ] Params infer from `parameters`; helper APIs use `Static<typeof parameters>` alias.
+- [ ] `label`, `description`, and useful parameter descriptions are present.
+- [ ] `promptGuidelines` bullets name the exact tool.
+- [ ] Execute signature is `(toolCallId, params, signal, onUpdate, ctx)`.
+- [ ] `onUpdate` uses optional chaining.
+- [ ] `signal` is forwarded to async operations.
+- [ ] Errors are thrown, not returned as fake success payloads.
+- [ ] Path tools strip leading `@`; mutating tools use `withFileMutationQueue()`.
+- [ ] Shared-state tools use safe concurrency or `executionMode: "sequential"`.
+- [ ] Large outputs are truncated with a full-output temp file.
+- [ ] Renderers return components, handle partial first, handle errors, and omit empty footers.